Skip to content

Commit 1f8988c

Browse files
xaduprexadupre
authored
Adds command faqref, runpython uses black (#21)
* Adds command faqref * rst * use black instead of pep8 * api * black * doc * fix doc * doc * doc
1 parent cb8c05e commit 1f8988c

File tree

14 files changed

+465
-34
lines changed

14 files changed

+465
-34
lines changed

‎CHANGELOGS.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ Change Logs
44
0.2.0
55
+++++
66

7+
* :pr:`21`: add sphinx extension faqref, runpython uses black
78
* :pr:`17`: add RST writer to output the documentation into pure RST format
89
* :pr:`16`: add command line nb2py to convert notebook to python files
910
* :pr:`11`: add function make_linkcode_resolve

‎README.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,7 @@ List of directives
8585
* `docassert <https://sdpython.github.io/doc/sphinx-runpython/dev/api/docassert.html>`_
8686
* `epkg <https://sdpython.github.io/doc/sphinx-runpython/dev/api/epkg.html>`_
8787
* `exref <https://sdpython.github.io/doc/sphinx-runpython/dev/api/blocdefs.html>`_
88+
* `faqref <https://sdpython.github.io/doc/sphinx-runpython/dev/api/blocdefs.html>`_
8889
* `gdot <https://sdpython.github.io/doc/sphinx-runpython/dev/api/gdot.html>`_
8990
* `mathdef <https://sdpython.github.io/doc/sphinx-runpython/dev/api/blocdefs.html>`_
9091
* `runpython <https://sdpython.github.io/doc/sphinx-runpython/dev/api/runpython.html>`_

‎_doc/api/blocdefs.rst‎

Lines changed: 57 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ differs depending on the content.
1111
exref
1212
=====
1313

14-
Location: :class:`exref <sphinx_runpython.blocdefs.sphinx_exref_extension.ExRef>`.
14+
Location: :class:`ExRef <sphinx_runpython.blocdefs.sphinx_exref_extension.ExRef>`.
1515

1616
In *conf.py*:
1717

@@ -45,10 +45,47 @@ Which gives:
4545
A reference can be added to this example :ref:`Example 1 <l-this-example>`.
4646
The title needs to be recalled.
4747

48+
faqref
49+
======
50+
51+
Location: :class:`FaqRef <sphinx_runpython.blocdefs.sphinx_faqref_extension.FaqRef>`.
52+
53+
In *conf.py*:
54+
55+
::
56+
57+
extensions = [ ...
58+
'sphinx_runpython.blocdefs.sphinx_faqref_extension']
59+
60+
faqref_include_faqrefs = True
61+
62+
An example:
63+
64+
::
65+
66+
.. faqref::
67+
:title: How to add an example?
68+
:tag: faq1
69+
:label: l-this-faq
70+
71+
This example, a piece of code...
72+
73+
Which gives:
74+
75+
.. faqref::
76+
:title: How to add an example?
77+
:tag: faq1
78+
:label: l-this-faq
79+
80+
This example, a piece of code...
81+
82+
A reference can be added to this example :ref:`Faq 1 <l-this-faq>`.
83+
The title needs to be recalled.
84+
4885
blocref
4986
=======
5087

51-
Location: :class:`blocref <sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef>`.
88+
Location: :class:`BlocRef <sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef>`.
5289

5390
In *conf.py*:
5491

@@ -85,7 +122,7 @@ The title needs to be recalled.
85122
mathdef
86123
=======
87124

88-
Location: :class:`mathdef <sphinx_runpython.blocdefs.sphinx_mathdef_extension.MathDef>`.
125+
Location: :class:`MathDef <sphinx_runpython.blocdefs.sphinx_mathdef_extension.MathDef>`.
89126

90127
In *conf.py*:
91128

@@ -123,7 +160,24 @@ Directives
123160
==========
124161

125162
.. autoclass:: sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef
163+
:members:
126164

127165
.. autoclass:: sphinx_runpython.blocdefs.sphinx_exref_extension.ExRef
166+
:members:
167+
168+
.. autoclass:: sphinx_runpython.blocdefs.sphinx_faqref_extension.FaqRef
169+
:members:
128170

129171
.. autoclass:: sphinx_runpython.blocdefs.sphinx_mathdef_extension.MathDef
172+
:members:
173+
174+
Nodes
175+
=====
176+
177+
.. autoclass:: sphinx_runpython.blocdefs.sphinx_blocref_extension.blocref_node
178+
179+
.. autoclass:: sphinx_runpython.blocdefs.sphinx_exref_extension.exref_node
180+
181+
.. autoclass:: sphinx_runpython.blocdefs.sphinx_faqref_extension.faqref_node
182+
183+
.. autoclass:: sphinx_runpython.blocdefs.sphinx_mathdef_extension.mathdef_node

‎_doc/api/blocdefs_list.rst‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,23 @@ Which gives:
2222
:tag: example
2323
:contents:
2424

25+
faqreflist
26+
==========
27+
28+
Example:
29+
30+
::
31+
32+
.. faqreflist::
33+
:tag: faq
34+
:contents:
35+
36+
Which gives:
37+
38+
.. faqreflist::
39+
:tag: faq
40+
:contents:
41+
2542
blocreflist
2643
===========
2744

‎_doc/api/runpython.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,7 @@ Interesting functions
189189

190190
.. autofunction:: sphinx_runpython.runpython.run_cmd
191191

192-
.. autofunction:: sphinx_runpython.runpython.sphinx_runpython_extension.remove_extra_spaces_and_pep8
192+
.. autofunction:: sphinx_runpython.runpython.sphinx_runpython_extension.remove_extra_spaces_and_black
193193

194194
Directive
195195
=========

‎_doc/conf.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
"sphinx_issues",
2121
"sphinx_runpython.blocdefs.sphinx_blocref_extension",
2222
"sphinx_runpython.blocdefs.sphinx_exref_extension",
23+
"sphinx_runpython.blocdefs.sphinx_faqref_extension",
2324
"sphinx_runpython.blocdefs.sphinx_mathdef_extension",
2425
"sphinx_runpython.collapse",
2526
"sphinx_runpython.docassert",
@@ -104,7 +105,7 @@
104105
}
105106

106107
epkg_dictionary = {
107-
"autopep8": "https://pypi.org/project/autopep8/",
108+
"black": "https://black.readthedocs.io/en/stable/index.html",
108109
"dot": "https://en.wikipedia.org/wiki/DOT_(graph_description_language)",
109110
"DOT": "https://en.wikipedia.org/wiki/DOT_(graph_description_language)",
110111
"JIT": "https://en.wikipedia.org/wiki/Just-in-time_compilation",

‎_unittests/ut_blocdefs/test_faqref_extension.py‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
import unittest
2+
from sphinx_runpython.process_rst import rst2html
3+
from sphinx_runpython.ext_test_case import ExtTestCase, ignore_warnings
4+
5+
6+
class TestFaqRefExtension(ExtTestCase):
7+
@ignore_warnings(PendingDeprecationWarning)
8+
def test_faqref(self):
9+
content = """
10+
test a directive
11+
================
12+
13+
before
14+
15+
.. faqref::
16+
:title: first todo
17+
:tag: bug
18+
:lid: id3
19+
20+
this code shoud appear___
21+
22+
after
23+
""".replace(
24+
" ", ""
25+
)
26+
content = content.replace('u"', '"')
27+
28+
html = rst2html(
29+
content,
30+
writer_name="rst",
31+
)
32+
33+
t1 = "this code shoud appear"
34+
if t1 not in html:
35+
raise AssertionError("ISSUE in " + html)
36+
37+
t1 = "after"
38+
if t1 not in html:
39+
raise AssertionError("ISSUE in " + html)
40+
41+
t1 = "first todo"
42+
if t1 not in html:
43+
raise AssertionError("ISSUE in " + html)
44+
45+
@ignore_warnings(PendingDeprecationWarning)
46+
def test_faqreflist(self):
47+
content = """
48+
test a directive
49+
================
50+
51+
before
52+
53+
.. faqref::
54+
:title: first todo
55+
:tag: freg
56+
:lid: id3
57+
58+
this code shoud appear___
59+
60+
middle
61+
62+
.. faqreflist::
63+
:tag: freg
64+
:sort: title
65+
66+
after
67+
""".replace(
68+
" ", ""
69+
)
70+
content = content.replace('u"', '"')
71+
72+
html = rst2html(content, writer_name="rst")
73+
74+
t1 = "this code shoud appear"
75+
if t1 not in html:
76+
raise AssertionError("ISSUE in " + html)
77+
78+
t1 = "after"
79+
if t1 not in html:
80+
raise AssertionError("ISSUE in " + html)
81+
82+
t1 = "first todo"
83+
if t1 not in html:
84+
raise AssertionError("ISSUE in " + html)
85+
86+
@ignore_warnings(PendingDeprecationWarning)
87+
def test_faqreflist_rst(self):
88+
content = """
89+
test a directive
90+
================
91+
92+
before
93+
94+
.. faqref::
95+
:title: first todo
96+
:tag: freg
97+
:lid: id3
98+
99+
this code shoud appear___
100+
101+
middle
102+
103+
.. faqreflist::
104+
:tag: freg
105+
:sort: title
106+
107+
after
108+
""".replace(
109+
" ", ""
110+
)
111+
content = content.replace('u"', '"')
112+
113+
rst = rst2html(content, writer_name="rst")
114+
115+
self.assertNotEmpty(rst)
116+
117+
118+
if __name__ == "__main__":
119+
unittest.main(verbosity=2)

‎pyproject.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ ignore_directives = [
88
"collapse",
99
"exref",
1010
"exreflist",
11+
"faqref",
12+
"faqreflist",
1113
"gdot",
1214
"image-sg",
1315
"mathdef",

‎requirements-dev.txt‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
autopep8
21
black
32
coverage
43
flake8

‎sphinx_runpython/blocdefs/sphinx_blocref_extension.py‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -85,10 +85,12 @@ class BlocRef(BaseAdmonition):
8585
:sort: title
8686
8787
This directive is used to highlight a bloc about
88-
anything @see cl BlocRef, a question @see cl FaqRef,
89-
a magic command @see cl NbRef, an example @see cl ExRef.
90-
It supports option *index* in most of the extensions
91-
so that the documentation can refer to it.
88+
anything :class:`sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef`,
89+
a question :class:`sphinx_runpython.blocdefs.sphinx_faqref_extension.FaqRef`,
90+
an example :class:`sphinx_runpython.blocdefs.sphinx_exref_extension.ExRef`.
91+
It supports option *index*
92+
in most of the extensions so that the documentation
93+
can refer to it.
9294
"""
9395

9496
node_class = blocref_node

0 commit comments

Comments
 (0)