Skip to content

Commit df74c46

Browse files
committed
refactor(docs): update documentation files and improve Sphinx configuration
1 parent 4fd0579 commit df74c46

15 files changed

Lines changed: 4395 additions & 7 deletions

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -232,3 +232,4 @@ cython_debug/
232232
/docs_version2/_static/logos/
233233
/docs/_static/logos/
234234
/docs/_build/
235+
/docs/changelog.md

brainpy/_base.py

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -44,12 +44,12 @@ class Neuron(brainstate.nn.Dynamics):
4444
for multi-dimensional input (e.g., ``100`` or ``(28, 28)``).
4545
spk_fun : Callable, optional
4646
Surrogate gradient function for the non-differentiable spike generation operation.
47-
Default is ``brainstate.surrogate.InvSquareGrad()``. Common alternatives include:
47+
Default is ``braintools.surrogate.InvSquareGrad()``. Common alternatives include:
4848
49-
- ``brainstate.surrogate.ReluGrad()``
50-
- ``brainstate.surrogate.SigmoidGrad()``
51-
- ``brainstate.surrogate.GaussianGrad()``
52-
- ``brainstate.surrogate.ATan()``
49+
- ``braintools.surrogate.ReluGrad()``
50+
- ``braintools.surrogate.SigmoidGrad()``
51+
- ``braintools.surrogate.GaussianGrad()``
52+
- ``braintools.surrogate.ATan()``
5353
spk_reset : str, optional
5454
Reset mechanism applied after spike generation. Default is ``'soft'``.
5555
@@ -150,7 +150,7 @@ class Neuron(brainstate.nn.Dynamics):
150150
... in_size=100,
151151
... tau=10*u.ms,
152152
... V_th=1.0*u.mV,
153-
... spk_fun=brainstate.surrogate.ReluGrad(),
153+
... spk_fun=braintools.surrogate.ReluGrad(),
154154
... spk_reset='soft'
155155
... )
156156
>>>

docs/_static/snn-simulation1.png

87.5 KB
Loading

docs/apis.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Neuron Models
1414
.. autosummary::
1515
:toctree: generated/
1616
:nosignatures:
17+
:template: classtemplate.rst
1718

1819
Neuron
1920
LIF
@@ -31,6 +32,8 @@ Synapse Models
3132
.. autosummary::
3233
:toctree: generated/
3334
:nosignatures:
35+
:template: classtemplate.rst
36+
3437

3538
Synapse
3639
Delta
@@ -48,6 +51,8 @@ Short-Term Plasticity
4851
.. autosummary::
4952
:toctree: generated/
5053
:nosignatures:
54+
:template: classtemplate.rst
55+
5156

5257
STP
5358
STD
@@ -60,6 +65,8 @@ Synaptic Output
6065
.. autosummary::
6166
:toctree: generated/
6267
:nosignatures:
68+
:template: classtemplate.rst
69+
6370

6471
CUBA
6572
COBA
@@ -72,6 +79,8 @@ Projection
7279
.. autosummary::
7380
:toctree: generated/
7481
:nosignatures:
82+
:template: classtemplate.rst
83+
7584

7685
Projection
7786
FullProjDelta
@@ -84,6 +93,8 @@ Readout
8493
.. autosummary::
8594
:toctree: generated/
8695
:nosignatures:
96+
:template: classtemplate.rst
97+
8798

8899
Readout
89100
Dense
@@ -96,6 +107,8 @@ Input Generators
96107
.. autosummary::
97108
:toctree: generated/
98109
:nosignatures:
110+
:template: classtemplate.rst
111+
99112

100113
spike_input
101114
latency_input

docs/checkpointing-en.ipynb

Lines changed: 675 additions & 0 deletions
Large diffs are not rendered by default.

docs/checkpointing-zh.ipynb

Lines changed: 675 additions & 0 deletions
Large diffs are not rendered by default.

docs/conf.py

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,20 @@
2222
import brainpy
2323
shutil.copytree('../images/', './_static/logos/', dirs_exist_ok=True)
2424
shutil.copyfile('../changelog.md', './changelog.md')
25+
shutil.rmtree('./generated')
26+
shutil.rmtree('./_build')
27+
2528

2629
# -- Project information -----------------------------------------------------
2730

2831
project = 'BrainPy'
2932
copyright = '2020-, BrainPy'
3033
author = 'BrainPy Team'
3134

35+
from highlight_test_lexer import fix_ipython2_lexer_in_notebooks
36+
37+
fix_ipython2_lexer_in_notebooks(os.path.dirname(os.path.abspath(__file__)))
38+
3239
# The full version, including alpha/beta/rc tags
3340
release = brainpy.__version__
3441

@@ -48,7 +55,8 @@
4855
'myst_nb',
4956
'matplotlib.sphinxext.plot_directive',
5057
'sphinx_thebe',
51-
'sphinx_design'
58+
'sphinx_design',
59+
'sphinx_math_dollar',
5260
# 'sphinx-mathjax-offline',
5361
]
5462
# Add any paths that contain custom static files (such as style sheets) here,

docs/highlight_test_lexer.py

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Copyright 2024 Brain Simulation Ecosystem Limited. All Rights Reserved.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
# ==============================================================================
15+
16+
17+
import glob
18+
import json
19+
import os
20+
import sys
21+
22+
23+
def fix_ipython2_lexer_in_notebooks(directory_path):
24+
"""
25+
批量修复指定目录中所有 Jupyter Notebook 文件的 ipython2 lexer 问题
26+
"""
27+
# 查找所有.ipynb文件
28+
notebook_files = glob.glob(os.path.join(directory_path, "*.ipynb"))
29+
30+
if not notebook_files:
31+
print(f"在目录 {directory_path} 中未找到任何 .ipynb 文件")
32+
return
33+
34+
fixed_count = 0
35+
36+
for file_path in notebook_files:
37+
try:
38+
with open(file_path, 'r', encoding='utf-8') as f:
39+
data = json.load(f)
40+
41+
needs_fix = False
42+
43+
# 检查并修复顶层元数据
44+
if 'metadata' in data:
45+
# 修复 language_info
46+
if 'language_info' in data['metadata']:
47+
lang_info = data['metadata']['language_info']
48+
if lang_info.get('name') == 'ipython2':
49+
lang_info['name'] = 'ipython3'
50+
needs_fix = True
51+
print(f"修复 {os.path.basename(file_path)}: 顶层 language_info.name")
52+
53+
if lang_info.get('pygments_lexer') == 'ipython2':
54+
lang_info['pygments_lexer'] = 'ipython3'
55+
needs_fix = True
56+
print(f"修复 {os.path.basename(file_path)}: 顶层 language_info.pygments_lexer")
57+
58+
# 修复 kernelspec
59+
if 'kernelspec' in data['metadata']:
60+
kernelspec = data['metadata']['kernelspec']
61+
if kernelspec.get('language') == 'ipython2':
62+
kernelspec['language'] = 'python'
63+
needs_fix = True
64+
print(f"修复 {os.path.basename(file_path)}: 顶层 kernelspec.language")
65+
66+
if kernelspec.get('name') == 'ipython2':
67+
kernelspec['name'] = 'python3'
68+
needs_fix = True
69+
print(f"修复 {os.path.basename(file_path)}: 顶层 kernelspec.name")
70+
71+
# 检查并修复单元格元数据
72+
for i, cell in enumerate(data.get('cells', [])):
73+
if 'metadata' in cell:
74+
# 修复单元格级别的语言设置
75+
if 'language' in cell['metadata'] and cell['metadata']['language'] == 'ipython2':
76+
cell['metadata']['language'] = 'ipython3'
77+
needs_fix = True
78+
print(f"修复 {os.path.basename(file_path)}: 单元格 {i} 的语言设置")
79+
80+
# 修复其他可能的 lexer 设置
81+
if 'pygments_lexer' in cell['metadata'] and cell['metadata']['pygments_lexer'] == 'ipython2':
82+
cell['metadata']['pygments_lexer'] = 'ipython3'
83+
needs_fix = True
84+
print(f"修复 {os.path.basename(file_path)}: 单元格 {i} 的 pygments_lexer 设置")
85+
86+
# 如果需要修复,保存文件
87+
if needs_fix:
88+
# 创建备份
89+
backup_path = file_path + '.backup'
90+
with open(backup_path, 'w', encoding='utf-8') as f:
91+
json.dump(data, f, indent=2, ensure_ascii=False)
92+
93+
# 保存修复后的文件
94+
with open(file_path, 'w', encoding='utf-8') as f:
95+
json.dump(data, f, indent=2, ensure_ascii=False)
96+
97+
fixed_count += 1
98+
print(f"已修复并备份: {os.path.basename(file_path)}")
99+
else:
100+
print(f"无需修复: {os.path.basename(file_path)}")
101+
102+
except Exception as e:
103+
print(f"处理文件 {file_path} 时出错: {str(e)}")
104+
105+
print(f"\n处理完成! 共修复了 {fixed_count} 个文件")
106+
return fixed_count
107+
108+
109+
if __name__ == "__main__":
110+
import os
111+
print(os.path.dirname(os.path.abspath(__file__)))
112+
113+
# 使用当前目录,或者指定您的文档目录路径
114+
target_directory = input("请输入包含.ipynb文件的目录路径(直接回车使用当前目录): ").strip()
115+
116+
if not target_directory:
117+
target_directory = "."
118+
119+
if not os.path.isdir(target_directory):
120+
print(f"错误: 目录 '{target_directory}' 不存在")
121+
sys.exit(1)
122+
123+
print(f"开始处理目录: {os.path.abspath(target_directory)}")
124+
fix_ipython2_lexer_in_notebooks(target_directory)

0 commit comments

Comments
 (0)