Skip to content

Commit 47a9583

Browse files
xaduprexadupre
committed
documentation
1 parent 0d0fe2d commit 47a9583

9 files changed

Lines changed: 250 additions & 26 deletions

File tree

‎_doc/api/collapse.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
.. _l-sphinx-collapse:
2+
3+
========
4+
collapse
5+
========
6+
7+
Location: :func:`collapse setup <sphinx_runpython.collapse.sphinx_collapse_extension.CollapseDirective>`.
8+
9+
This extension adds a button to hide or show a limited part of the
10+
documentation.
11+
12+
In *conf.py*:
13+
14+
::
15+
16+
extensions = [ ...
17+
'sphinx_runpython.collapse']
18+
19+
.. sidebar:: collapse
20+
21+
::
22+
23+
.. collapse::
24+
25+
Show or hide a part of the documentation.
26+
27+
.. collapse::
28+
29+
Show or hide a part of the documentation.

‎_doc/api/epkg.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ In *conf.py*:
1111
::
1212

1313
extensions = [ ...
14-
'pyquickhelper.sphinxext.sphinx_epkg_extension']
14+
'sphinx_runpython.epkg.sphinx_epkg_extension']
1515

1616
epkg_dictionary = {
1717
'pandoc': 'http://johnmacfarlane.net/pandoc/', # 1

‎_doc/api/index.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,21 @@
33
API
44
===
55

6+
Extensions
7+
==========
8+
69
.. toctree::
710
:maxdepth: 1
811

12+
collapse
913
epkg
14+
runpython
15+
16+
Helpers
17+
=======
18+
19+
.. toctree::
20+
:maxdepth: 1
21+
1022
helpers
1123
import_object_helper

‎_doc/api/runpython.rst‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
.. _l-sphinx-runpython:
2+
3+
=========
4+
runpython
5+
=========
6+
7+
Description
8+
===========
9+
10+
Location: :py:class:`RunPythonDirective <sphinx_runpython.runpython.sphinx_runpython_extension.RunPythonDirective>`.
11+
12+
In *conf.py*:
13+
14+
::
15+
16+
extensions = [ ...
17+
'sphinx_runpython.runpython.sphinxext_runpython_extension']
18+
19+
Documentation means many examples which needs to be updated when a change
20+
happen unless the documentation runs the example itself and update its output.
21+
That's what this directive does. It adds as raw text whatever comes out
22+
throught the standard output.
23+
24+
.. sidebar:: runpython
25+
26+
::
27+
28+
.. runpython::
29+
:showcode:
30+
31+
import os
32+
for i, name in enumerate(os.listdir(".")):
33+
print(i, name)
34+
35+
.. runpython::
36+
:showcode:
37+
38+
import os
39+
for i, name in enumerate(os.listdir(".")):
40+
print(i, name)
41+
42+
The output can also be compiled as RST format and the code can be hidden.
43+
It is useful if the documentation is a copy/paste of some external process
44+
or function. This function can be directly called from the documentation.
45+
The output must be converted into RST format. It is then added to the
46+
documentation. It is quite useful to display the version of some installed
47+
modules.
48+
49+
.. sidebar:: runpython and rst
50+
51+
::
52+
53+
.. runpython::
54+
:rst:
55+
56+
import pandas, numpy, sphinx
57+
58+
for i, mod in [sphinx, pandas, numpy]:
59+
print("* version of *{0}*: *{1}*".format(
60+
getattr(mod, "__name__"), getattr(mod, "__version__"))
61+
62+
.. runpython::
63+
:rst:
64+
65+
import os
66+
for i, name in enumerate(os.listdir(".")):
67+
print("* file **{0}**: *{1}*".format(i, name))
68+
69+
If the code throws an exception (except a syntax error),
70+
it can be caught by adding the option ``:exception:``.
71+
The directive displays the traceback.
72+
73+
.. runpython::
74+
:showcode:
75+
:exception:
76+
77+
import os
78+
for i, name in enumerate(os.listdir("not existing")):
79+
pass
80+
81+
.. _l-image-rst-runpython:
82+
83+
The directive can also be used to display images
84+
with a tweak however. It consists in writing *rst*
85+
code. The variable ``__WD__`` indicates the local
86+
directory.
87+
88+
.. runpython::
89+
:showcode:
90+
91+
print('__WD__=%r' % __WD__)
92+
93+
Applied to images...
94+
95+
.. sidebar:: runpython and image
96+
97+
::
98+
99+
.. runpython::
100+
:rst:
101+
102+
import matplotlib.pyplot as plt
103+
fig, ax = plt.subplots(1, 1, figsize=(4, 4))
104+
ax.plot([0, 1], [0, 1], '--')
105+
fig.savefig(os.path.join(__WD__, "oo.png"))
106+
107+
text = ".. image:: oo.png\\\\n :width: 202px"
108+
print(text)
109+
110+
The image needs to be save in the same folder than
111+
the *rst* file.
112+
113+
.. runpython::
114+
:rst:
115+
116+
import matplotlib.pyplot as plt
117+
fig, ax = plt.subplots(1, 1, figsize=(4, 4))
118+
ax.plot([0, 1], [0, 1], '--')
119+
fig.savefig(os.path.join(__WD__, "oo.png"))
120+
121+
text = ".. image:: oo.png\\\\n :width: 201px"
122+
print(text)
123+
124+
Option ``:toggle:`` can hide the code or the output or both
125+
but let the user unhide it by clicking on a button.
126+
127+
.. sidebar:: runpython and image
128+
129+
::
130+
131+
.. runpython::
132+
:showcode:
133+
:toggle: out
134+
135+
for i in range(0, 10):
136+
print("i=", i)
137+
138+
.. runpython::
139+
:showcode:
140+
:toggle: out
141+
142+
for i in range(0, 10):
143+
print("i=", i)
144+
145+
The last option of *runpython* allows the user to keep
146+
some context from one execution to the next one.
147+
148+
.. sidebar:: runpython and context
149+
150+
::
151+
152+
.. runpython::
153+
:showcode:
154+
:store:
155+
156+
a_to_keep = 5
157+
print("a_to_keep", "=", a_to_keep)
158+
159+
.. runpython::
160+
:showcode:
161+
:restore:
162+
163+
a_to_keep += 5
164+
print("a_to_keep", "=", a_to_keep)
165+
166+
.. runpython::
167+
:showcode:
168+
:store:
169+
170+
a_to_keep = 5
171+
print("a_to_keep", "=", a_to_keep)
172+
173+
.. runpython::
174+
:showcode:
175+
:restore:
176+
177+
a_to_keep += 5
178+
print("a_to_keep", "=", a_to_keep)
179+
180+
.. index:: sphinx-autorun
181+
182+
`sphinx-autorun <https://pypi.org/project/sphinx-autorun/>`_ offers a similar
183+
service except it cannot produce compile :epkg:`RST` content,
184+
hide the source and a couple of other options.
185+
186+
Interesting functions
187+
=====================
188+
189+
.. autofunction:: sphinx_runpython.runpython.run_cmd

‎_doc/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
"sphinx.ext.githubpages",
1515
"sphinx_gallery.gen_gallery",
1616
"matplotlib.sphinxext.plot_directive",
17+
"sphinx_runpython.collapse",
1718
"sphinx_runpython.epkg",
1819
"sphinx_runpython.runpython",
1920
]

‎sphinx_runpython/import_object_helper.py‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,6 @@ def import_object(docname, kind, use_init=True) -> Tuple[object, str]:
2424
Extracts an object defined by its name including the module name.
2525
2626
:param docname: full name of the object
27-
(example: ``pyquickhelper.sphinxext.sphinx_docassert_extension.import_object``)
2827
:param kind: ``'function'`` or ``'class'`` or ``'kind'``
2928
:param use_init: return the constructor instead of the class
3029
:return: tuple(object, name)
@@ -124,7 +123,6 @@ def import_any_object(docname: str, use_init: bool = True) -> Tuple[object, str,
124123
Extracts an object defined by its name including the module name.
125124
126125
:param docname: full name of the object
127-
(example: ``pyquickhelper.sphinxext.sphinx_docassert_extension.import_object``)
128126
:param use_init: return the constructor instead of the class
129127
:returns: tuple(object, name, kind)
130128
:raises: :epkg:`*py:ImportError` if unable to import

‎sphinx_runpython/runpython/__init__.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
from .run_cmd import run_cmd
12
from .sphinx_runpython_extension import setup
23

3-
__all__ = ["setup"]
4+
__all__ = ["run_cmd", "setup"]

‎sphinx_runpython/runpython/run_cmd.py‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -169,13 +169,10 @@ def run_cmd(
169169
:param prefix_log: add a prefix to a line before printing it
170170
:return: content of stdout, stdres (only if wait is True)
171171
172-
.. exref::
173-
:title: Run a program using the command line
172+
::
174173
175-
::
176-
177-
from pyquickhelper.loghelper import run_cmd
178-
out, err = run_cmd("python setup.py install", wait=True)
174+
from sphinx_runpython.runpython import run_cmd
175+
out, err = run_cmd("python setup.py install", wait=True)
179176
180177
If you are using this function to run :epkg:`git` function, parameter
181178
``shell`` must be True.

‎sphinx_runpython/runpython/sphinx_runpython_extension.py‎

Lines changed: 13 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -489,28 +489,25 @@ class RunPythonDirective(Directive):
489489
Extracts script to run described by ``.. runpython::``
490490
and modifies the documentation.
491491
492-
.. exref::
493-
:title: A python script which generates documentation
494-
495-
The following code prints the version of Python
496-
on the standard output. It is added to the documentation::
497-
498-
.. runpython::
499-
:showcode:
500-
501-
import sys
502-
print("sys.version_info=", str(sys.version_info))
503-
504-
If give the following results:
492+
The following code prints the version of Python
493+
on the standard output. It is added to the documentation::
505494
506495
.. runpython::
496+
:showcode:
507497
508498
import sys
509499
print("sys.version_info=", str(sys.version_info))
510500
511-
Options *showcode* can be used to display the code.
512-
The option *rst* will assume the output is in RST format and must be
513-
interpreted. *showout* will complement the RST output with the raw format.
501+
If give the following results:
502+
503+
.. runpython::
504+
505+
import sys
506+
print("sys.version_info=", str(sys.version_info))
507+
508+
Options *showcode* can be used to display the code.
509+
The option *rst* will assume the output is in RST format and must be
510+
interpreted. *showout* will complement the RST output with the raw format.
514511
515512
The directive has a couple of options:
516513

0 commit comments

Comments
 (0)