upgrade documentation

Author: chaoming0625

changelog.rst

@@ -2,6 +2,15 @@ Release notes (brainpy)
 #######################
 
 
+
+
+.. note::
+
+   All history release notes please see `GitHub releases <https://github.com/brainpy/BrainPy/releases>`_.
+
+
+
+
 brainpy 2.2.x
 *************
 
@@ -10,12 +19,6 @@ tackling the shortcomings of brainpy 2.1.x generation,
 effectively bringing it to research needs and standards.
 
 
-.. note::
-
-   All history release notes please see `GitHub <https://github.com/brainpy/BrainPy/releases>`_.
-
-
-
 
 Version 2.2.1 (2022.09.09)
 ==========================

docs/_static/numpy_arrays.png

@@ -0,0 +1,32 @@
+{{ fullname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   .. automethod:: __init__
+
+   {% block methods %}
+
+   {% if methods %}
+   .. rubric:: Methods
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/class_template.rst

@@ -10,13 +10,9 @@
     :maxdepth: 1
 
     auto/math/variables
-    auto/math/delay_vars
-    auto/math/jit
+    auto/math/object_transform
     auto/math/operators
-    auto/math/controls
-    auto/math/autograd
+    auto/math/delay_vars
     auto/math/activations
-    auto/math/function
     math/comparison
     auto/math/setting
-    math_compat

docs/apis/math.rst

@@ -35,23 +35,23 @@ def get_class_funcs(module):
   return classes, functions, others
 
 
-def write_module(module_name, filename, header=None):
+def write_module(module_name, filename, header=None, template=False):
   module = importlib.import_module(module_name)
   classes, functions, others = get_class_funcs(module)
 
   fout = open(filename, 'w')
   # write header
   if header is None:
     header = f'``{module_name}`` module'
-  else:
-    header = header
   fout.write(header + '\n')
   fout.write('=' * len(header) + '\n\n')
   fout.write(f'.. currentmodule:: {module_name} \n')
   fout.write(f'.. automodule:: {module_name} \n\n')
 
   # write autosummary
   fout.write('.. autosummary::\n')
+  if template:
+    fout.write('   :template: class_template.rst\n')
   fout.write('   :toctree: generated/\n\n')
   for m in functions:
     fout.write(f'   {m}\n')
@@ -205,16 +205,20 @@ def generate_train_docs(path='apis/auto/train/'):
     os.makedirs(path)
   write_module(module_name='brainpy.train.base',
                filename=os.path.join(path, 'base.rst'),
-               header='Base Training Class')
+               header='Base Training Class',
+               template=False)
   write_module(module_name='brainpy.train.online',
                filename=os.path.join(path, 'online.rst'),
-               header='Online Training Method')
+               header='Online Training Method',
+               template=False)
   write_module(module_name='brainpy.train.offline',
                filename=os.path.join(path, 'offline.rst'),
-               header='Offline Training Method')
+               header='Offline Training Method',
+               template=False)
   write_module(module_name='brainpy.train.back_propagation',
                filename=os.path.join(path, 'back_propagation.rst'),
-               header='Back-propagation Training Method')
+               header='Back-propagation Training Method',
+               template=False)
 
 
 def generate_base_docs(path='apis/auto/'):
@@ -491,43 +495,38 @@ def generate_math_docs(path='apis/auto/math/'):
 
   module_and_name = [
     ('pre_syn_post',   '``pre-syn-post`` Transformations',),
-    ('sparse_matmul', 'Sparse Matrix Multiplication',),
-    ('event_matmul', 'Event-based Matrix Multiplication',),
-    ('spikegrad',      'Surrogate Gradients for Spike Operation',),
+    ('surrogate',      'Surrogate Gradients',),
     ('op_register',    'Operator Registration',),
     ('wrap_jax',       'Other Operators',),
   ]
   write_submodules(module_name='brainpy.math.operators',
                    filename=os.path.join(path, 'operators.rst'),
-                   header='Sparse & Event-based Operators',
+                   header='Brain Dynamics Modeling Operators',
+                   submodule_names=[k[0] for k in module_and_name],
+                   section_names=[k[1] for k in module_and_name])
+
+  module_and_name = [
+    ('autograd', 'Automatic Differentiation'),
+    ('controls', 'Control Flows'),
+    # ('parallels', 'Parallel Compilation'),
+    ('jit', 'JIT Compilation'),
+    ('function', 'Function to Object'),
+  ]
+  write_submodules(module_name='brainpy.math.object_transform',
+                   filename=os.path.join(path, 'object_transform.rst'),
+                   header='Object-oriented Transformation',
                    submodule_names=[k[0] for k in module_and_name],
                    section_names=[k[1] for k in module_and_name])
 
   write_module(module_name='brainpy.math.activations',
                filename=os.path.join(path, 'activations.rst'),
                header='Activation Functions')
-  write_module(module_name='brainpy.math.autograd',
-               filename=os.path.join(path, 'autograd.rst'),
-               header='Automatic Differentiation')
-  write_module(module_name='brainpy.math.controls',
-               filename=os.path.join(path, 'controls.rst'),
-               header='Control Flows')
-
-  write_module(module_name='brainpy.math.parallels',
-               filename=os.path.join(path, 'parallels.rst'),
-               header='Parallel Compilation')
-  write_module(module_name='brainpy.math.jit',
-               filename=os.path.join(path, 'jit.rst'),
-               header='JIT Compilation')
-  write_module(module_name='brainpy.math.jaxarray',
+  write_module(module_name='brainpy.math.ndarray',
                filename=os.path.join(path, 'variables.rst'),
                header='Math Variables')
   write_module(module_name='brainpy.math.setting',
                filename=os.path.join(path, 'setting.rst'),
                header='Setting')
-  write_module(module_name='brainpy.math.function',
-               filename=os.path.join(path, 'function.rst'),
-               header='Function')
   write_module(module_name='brainpy.math.delayvars',
                filename=os.path.join(path, 'delay_vars.rst'),
                header='Delay Variables')

docs/auto_generater.py

@@ -65,13 +65,14 @@
   'sphinx.ext.autosummary',
   'sphinx.ext.intersphinx',
   'sphinx.ext.mathjax',
-  # 'sphinx-mathjax-offline',
   'sphinx.ext.napoleon',
   'sphinx.ext.viewcode',
   'sphinx_autodoc_typehints',
   'myst_nb',
   'matplotlib.sphinxext.plot_directive',
-  'sphinx_thebe'
+  'sphinx_thebe',
+
+  # 'sphinx-mathjax-offline',
 ]
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -102,9 +103,9 @@
     "dollarmath",
     "amsmath",
     "deflist",
+    "colon_fence",
     # "html_admonition",
     # "html_image",
-    "colon_fence",
     # "smartquotes",
     # "replacements",
     # "linkify",

docs/conf.py

@@ -44,6 +44,20 @@ high-performance Brain Dynamics Programming (BDP). Among its key ingredients, Br
    tutorial_analysis/index
 
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Advanced Tutorials
+
+   tutorial_advanced/variables.ipynb
+   tutorial_advanced/base_and_collector.ipynb
+   tutorial_advanced/compilation.ipynb
+   tutorial_advanced/differentiation.ipynb
+   tutorial_advanced/adavanced_lowdim_analysis.ipynb
+   tutorial_advanced/operator_customization.ipynb
+   tutorial_advanced/interoperation.ipynb
+
+
+
 .. toctree::
    :maxdepth: 1
    :caption: Toolboxes
@@ -60,25 +74,12 @@ high-performance Brain Dynamics Programming (BDP). Among its key ingredients, Br
    tutorial_toolbox/inputs
 
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Advanced Tutorials
-
-   tutorial_advanced/variables.ipynb
-   tutorial_advanced/base_and_collector.ipynb
-   tutorial_advanced/compilation.ipynb
-   tutorial_advanced/differentiation.ipynb
-   tutorial_advanced/adavanced_lowdim_analysis.ipynb
-   tutorial_advanced/operator_customization.ipynb
-   tutorial_advanced/interoperation.ipynb
-
-
-
 .. toctree::
    :maxdepth: 1
    :caption: Frequently Asked Questions
 
    tutorial_FAQs/citing_and_publication
+   tutorial_FAQs/uniqueness_of-brainpy-math
 
 
 .. toctree::