Skip to content

Commit c296117

Browse files
xaduprexadupre
authored
Adds bloc definition, mathdef, blocref, exref (#4)
* Adds bloc definition * clean * fix documentation * doc * docu * doc * sphinx * label * doc * fix warnings * doc * README
1 parent 90d24fd commit c296117

24 files changed

+2501
-22
lines changed

‎.github/workflows/documentation.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ jobs:
1616
# Used to host cibuildwheel
1717
- uses: actions/setup-python@v4
1818
with:
19-
python-version: '3.10'
19+
python-version: '3.11'
2020

2121
- name: Install requirements
2222
run: python -m pip install -r requirements.txt
@@ -28,7 +28,7 @@ jobs:
2828
run: python -m pip install -e .
2929

3030
- name: Documentation
31-
run: python -m sphinx ./_doc ./dist/html
31+
run: python -m sphinx ./_doc ./dist/html -n
3232

3333
- uses: actions/upload-artifact@v3
3434
with:

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ dist/*
99
build/*
1010
.eggs/*
1111
*egg-info/*
12+
temp_*
13+
_doc/api/oo.png
1214
_doc/examples/_cache/*
1315
_doc/auto_examples/*
1416
_doc/examples/plot_*.png

‎CHANGELOGS.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
Change Logs
22
===========
33

4+
0.2.0
5+
+++++
6+
7+
* :pr:`4`: add sphinx extension mathdef, exref, blocref
8+
49
0.1.0
510
+++++
611

‎README.rst‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ The library is released on
3232
`pypi/sphinx-runpython <https://pypi.org/project/sphinx-runpython/>`_
3333
and its documentation is published at
3434
`sphinx-runpython
35-
<http://www.xavierdupre.fr/app/sphinx-runpython/helpsphinx/index.html>`_.
35+
<https://sdpython.github.io/doc/sphinx-runpython/>`_.
3636

3737
epkg
3838
++++
@@ -73,3 +73,13 @@ Executes code in the documentation and adds it to documentation.
7373
>>>
7474

7575
python code
76+
77+
List of directives
78+
++++++++++++++++++
79+
80+
* `blocref <https://sdpython.github.io/doc/sphinx-runpython/api/blocdefs.html>_`
81+
* `collapse <https://sdpython.github.io/doc/sphinx-runpython/api/collapse.html>`_
82+
* `epkg <https://sdpython.github.io/doc/sphinx-runpython/api/epkg.html>`_
83+
* `exref <https://sdpython.github.io/doc/sphinx-runpython/api/blocdefs.html>_`
84+
* `mathdef <https://sdpython.github.io/doc/sphinx-runpython/api/blocdefs.html>_`
85+
* `runpython <https://sdpython.github.io/doc/sphinx-runpython/api/runpython.html>_`

‎_doc/api/blocdefs.rst‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
.. _l-blocdefs:
2+
3+
=======================
4+
blocref, exref, mathdef
5+
=======================
6+
7+
They pretty much follows the same design. They highlight a paragraph
8+
and this paragraph can be recalled anywhere on another page. Some options
9+
differs depending on the content.
10+
11+
exref
12+
=====
13+
14+
Location: :class:`exref <sphinx_runpython.blocdefs.sphinx_exref_extension.ExRef>`.
15+
16+
In *conf.py*:
17+
18+
::
19+
20+
extensions = [ ...
21+
'sphinx_runpython.blocdefs.sphinx_exref_extension']
22+
23+
exref_include_exrefs = True
24+
25+
An example:
26+
27+
::
28+
29+
.. exref::
30+
:title: How to add an example?
31+
:tag: example
32+
:label: l-this-example
33+
34+
This example, a piece of code...
35+
36+
Which gives:
37+
38+
.. exref::
39+
:title: How to add an example?
40+
:tag: example
41+
:label: l-this-example
42+
43+
This example, a piece of code...
44+
45+
A reference can be added to this example :ref:`Example 1 <l-this-example>`.
46+
The title needs to be recalled.
47+
48+
blocref
49+
=======
50+
51+
Location: :class:`blocref <sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef>`.
52+
53+
In *conf.py*:
54+
55+
::
56+
57+
extensions = [ ...
58+
'sphinx_runpython.blocdefs.sphinx_blocref_extension']
59+
60+
blocref_include_blocrefs = True
61+
62+
An example:
63+
64+
::
65+
66+
.. blocref::
67+
:title: How to add a bloc?
68+
:tag: bloc
69+
:label: l-this-bloc
70+
71+
A bloc...
72+
73+
Which gives:
74+
75+
.. blocref::
76+
:title: How to add a bloc?
77+
:tag: bloc
78+
:label: l-this-bloc
79+
80+
A bloc...
81+
82+
A reference can be added to this bloc :ref:`Bloc A <l-this-bloc>`.
83+
The title needs to be recalled.
84+
85+
mathdef
86+
=======
87+
88+
Location: :class:`mathdef <sphinx_runpython.blocdefs.sphinx_mathdef_extension.MathDef>`.
89+
90+
In *conf.py*:
91+
92+
::
93+
94+
extensions = [ ...
95+
'sphinx_runpython.blocdefs.sphinx_mathdef_extension']
96+
97+
mathdef_include_mathdefs = True
98+
99+
An example:
100+
101+
::
102+
103+
.. mathdef::
104+
:title: How to add a definition?
105+
:tag: definition
106+
:label: l-this-def
107+
108+
A definition...
109+
110+
Which gives:
111+
112+
.. mathdef::
113+
:title: How to add a definition?
114+
:tag: definition
115+
:label: l-this-def
116+
117+
A definition...
118+
119+
A reference can be added to this definition :ref:`Def 1 <l-this-def>`.
120+
The title needs to be recalled.
121+
122+
Directives
123+
==========
124+
125+
.. autoclass:: sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef
126+
127+
.. autoclass:: sphinx_runpython.blocdefs.sphinx_exref_extension.ExRef
128+
129+
.. autoclass:: sphinx_runpython.blocdefs.sphinx_mathdef_extension.MathDef

‎_doc/api/blocdefs_list.rst‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
===================================
2+
blocreflist, exreflist, mathdeflist
3+
===================================
4+
5+
These extensions can recall the blocs defined by
6+
:ref:`l-blocdefs`.
7+
8+
exreflist
9+
=========
10+
11+
Example:
12+
13+
::
14+
15+
.. exreflist::
16+
:tag: example
17+
:contents:
18+
19+
Which gives:
20+
21+
.. exreflist::
22+
:tag: example
23+
:contents:
24+
25+
blocreflist
26+
===========
27+
28+
An example:
29+
30+
::
31+
32+
.. blocreflist::
33+
:tag: bloc
34+
:contents:
35+
36+
Which gives:
37+
38+
.. blocreflist::
39+
:tag: bloc
40+
:contents:
41+
42+
mathdeflist
43+
===========
44+
45+
An example:
46+
47+
::
48+
49+
.. mathdeflist::
50+
:tag: definition
51+
:contents:
52+
53+
Which gives:
54+
55+
.. mathdeflist::
56+
:tag: definition
57+
:contents:

‎_doc/api/collapse.rst‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ In *conf.py*:
1212
::
1313

1414
extensions = [ ...
15-
'sphinx_runpython.collapse']
15+
'sphinx_runpython.collapse',
16+
]
1617

1718
.. sidebar:: collapse
1819

@@ -25,3 +26,8 @@ In *conf.py*:
2526
.. collapse::
2627

2728
Show or hide a part of the documentation.
29+
30+
Directive
31+
=========
32+
33+
.. autoclass:: sphinx_runpython.collapse.sphinx_collapse_extension.CollapseDirective

‎_doc/api/epkg.rst‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,18 @@
1+
.. _l-sphinx-epkg:
2+
13
====
24
epkg
35
====
46

5-
Location: :func:`epkg_role <sphinx_runpython.epkg.sphinxext_epkg_extension.epkg_role>`.
7+
Location: :class:`epkg_role <sphinx_runpython.epkg.sphinx_epkg_extension.epkg_role>`.
68

79
In *conf.py*:
810

911
::
1012

1113
extensions = [ ...
12-
'sphinx_runpython.epkg.sphinx_epkg_extension']
14+
'sphinx_runpython.epkg',
15+
]
1316

1417
epkg_dictionary = {
1518
'pandoc': 'http://johnmacfarlane.net/pandoc/', # 1
@@ -58,3 +61,8 @@ value is a callable <https://github.com/sphinx-doc/sphinx/issues/1424>`_),
5861
``my_custom_links`` needs to be replaced by:
5962
``("module_where_it_is_defined.my_custom_links", None)``.
6063
The role *epkg* will import it based on its name.
64+
65+
Directive
66+
=========
67+
68+
.. autofunction:: sphinx_runpython.epkg.sphinx_epkg_extension.epkg_role

‎_doc/api/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ Extensions
1212
collapse
1313
epkg
1414
runpython
15+
blocdefs
16+
blocdefs_list
1517

1618
Helpers
1719
=======

‎_doc/api/runpython.rst‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,15 @@ runpython
55
Description
66
===========
77

8-
Location: :py:class:`RunPythonDirective <sphinx_runpython.runpython.sphinx_runpython_extension.RunPythonDirective>`.
8+
Location: :class:`RunPythonDirective <sphinx_runpython.runpython.sphinx_runpython_extension.RunPythonDirective>`.
99

1010
In *conf.py*:
1111

1212
::
1313

1414
extensions = [ ...
15-
'sphinx_runpython.runpython.sphinxext_runpython_extension']
15+
'sphinx_runpython.runpython',
16+
]
1617

1718
Documentation means many examples which needs to be updated when a change
1819
happen unless the documentation runs the example itself and update its output.
@@ -55,7 +56,8 @@ modules.
5556

5657
for i, mod in [sphinx, pandas, numpy]:
5758
print("* version of *{0}*: *{1}*".format(
58-
getattr(mod, "__name__"), getattr(mod, "__version__"))
59+
getattr(mod, "__name__"), getattr(mod, "__version__"
60+
))
5961

6062
.. runpython::
6163
:rst:
@@ -100,7 +102,7 @@ Applied to images...
100102
ax.plot([0, 1], [0, 1], '--')
101103
fig.savefig(os.path.join(__WD__, "oo.png"))
102104

103-
text = ".. image:: oo.png\\\\n :width: 202px"
105+
text = ".. image:: oo.png"
104106
print(text)
105107

106108
The image needs to be save in the same folder than
@@ -114,7 +116,7 @@ the *rst* file.
114116
ax.plot([0, 1], [0, 1], '--')
115117
fig.savefig(os.path.join(__WD__, "oo.png"))
116118

117-
text = ".. image:: oo.png\\\\n :width: 201px"
119+
text = ".. image:: oo.png\n :width: 201px"
118120
print(text)
119121

120122
Option ``:toggle:`` can hide the code or the output or both
@@ -182,4 +184,11 @@ hide the source and a couple of other options.
182184
Interesting functions
183185
=====================
184186

185-
.. autofunction:: sphinx_runpython.runpython.run_cmd
187+
.. autofunction:: sphinx_runpython.runpython.run_cmd
188+
189+
.. autofunction:: sphinx_runpython.runpython.sphinx_runpython_extension.remove_extra_spaces_and_pep8
190+
191+
Directive
192+
=========
193+
194+
.. autoclass:: sphinx_runpython.runpython.sphinx_runpython_extension.RunPythonDirective

0 commit comments

Comments
 (0)