Visitar URL original
Adds extension gdot (#6) · sdpython/sphinx-runpython@6272fb4 · GitHub
Skip to content

Commit 6272fb4

Browse files
xaduprexadupre
authored
Adds extension gdot (#6)
* Add extension gdot * ci * syntax * syntax * syntax * syntax * syntax * syntax * syntax * syntax * out * out * dot * fix dot * black * fix * png * fix documentation
1 parent 4a56438 commit 6272fb4

18 files changed

Lines changed: 1289 additions & 29 deletions

‎.github/workflows/documentation.yml‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ jobs:
1313
steps:
1414
- uses: actions/checkout@v3
1515

16+
- uses: tlylt/install-graphviz@v1
17+
1618
# Used to host cibuildwheel
1719
- uses: actions/setup-python@v4
1820
with:
@@ -28,19 +30,21 @@ jobs:
2830
run: python -m pip install -e .
2931

3032
- name: Documentation
31-
run: python -m sphinx ./_doc ./dist/html -n
33+
run: python -m sphinx ./_doc ./dist/html -n -w doc.txt
3234

33-
- name: Check Documentation Output
34-
if: steps.documentation.outputs.documentationOutput != 'Hello, GitHub Actions!'
35-
run: |
36-
message="${{ steps.documentation.outputs.message }}"
35+
- name: Summary
36+
run: cat doc.txt
3737

38-
if [[ $message == *"ERROR"* ]]; then
39-
echo "Sphinx output has errors."
38+
- name: Check for errors and warnings
39+
run: |
40+
if [[ $(grep ERROR doc.txt) ]]; then
41+
echo "Documentation produces errors."
42+
grep ERROR doc.txt
4043
exit 1
4144
fi
42-
if [[ $message == *"WARNING"* ]]; then
43-
echo "Sphinx output has warnings."
45+
if [[ $(grep WARNING doc.txt) ]]; then
46+
echo "Documentation produces warnings."
47+
grep WARNING doc.txt
4448
exit 1
4549
fi
4650

‎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:`6`: add sphinx extension gdot
78
* :pr:`5`: add sphinx extension docassert
89
* :pr:`4`: add sphinx extension mathdef, exref, blocref
910

‎_doc/api/collapse.rst‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,6 @@ a section.
99
Usage
1010
=====
1111

12-
Location: :func:`collapse setup <sphinx_runpython.collapse.sphinx_collapse_extension.CollapseDirective>`.
13-
14-
This extension adds a button to hide or show a limited part of the
15-
documentation.
16-
1712
In *conf.py*:
1813

1914
::

‎_doc/api/docassert.rst‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,6 @@ undocumented parameters.
88
Usage
99
=====
1010

11-
Location: :class:`docassert setup <sphinx_runpython.docassert.sphinx_docassert_extension.OverrideDocFieldTransformer>`.
12-
1311
This extension does nothing but generating warnings if a function or a class
1412
documents a misspelled parameter (not in the signature) or if one
1513
parameter is missing from the documentation.

‎_doc/api/epkg.rst‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,6 @@ only show the anchor in the documentation.
1010
Usage
1111
=====
1212

13-
Location: :class:`epkg_role <sphinx_runpython.epkg.sphinx_epkg_extension.epkg_role>`.
14-
1513
In *conf.py*:
1614

1715
::

‎_doc/api/gdot.rst‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
====
2+
gdot
3+
====
4+
5+
This directive displays :epkg:`dot` graph in the documentation.
6+
It relies on :epkg:`Graphviz`.
7+
8+
Usage
9+
=====
10+
11+
In *conf.py*:
12+
13+
::
14+
15+
extensions = [ ...
16+
'sphinx.ext.graphviz',
17+
'sphinx_runpython.gdot',
18+
]
19+
20+
One example:
21+
22+
::
23+
24+
.. gdot::
25+
:format: png
26+
27+
digraph foo {
28+
"bar" -> "baz" -> "end";
29+
}
30+
31+
Which gives:
32+
33+
.. gdot::
34+
:format: png
35+
36+
digraph foo {
37+
"bar" -> "baz" -> "end";
38+
}
39+
40+
The output format is an image (:epkg:`PNG`).
41+
It can be changed to use :epkg:`SVG` but
42+
it requires `viz.js` to be displayed.
43+
44+
::
45+
46+
.. gdot::
47+
:format: svg
48+
49+
digraph foo {
50+
"bar" -> "baz" -> "svg";
51+
}
52+
53+
.. gdot::
54+
:format: svg
55+
56+
digraph foo {
57+
"bar" -> "baz" -> "svg";
58+
}
59+
60+
The graph may also be the output of a script.
61+
62+
::
63+
64+
.. gdot::
65+
:format: svg
66+
:script: AFTER-THIS
67+
68+
print("before the graph")
69+
print("AFTER-THIS", """
70+
digraph foo {
71+
"bar" -> "baz" -> "script";
72+
}
73+
""")
74+
75+
.. gdot::
76+
:format: svg
77+
:script: AFTER-THIS
78+
79+
print("before the graph")
80+
print("AFTER-THIS", """
81+
digraph foo {
82+
"bar" -> "baz" -> "script";
83+
}
84+
""")
85+
86+
Finally, the tag `:process:` can be used to run the script in
87+
a separate process.
88+
89+
Directive
90+
=========
91+
92+
.. autoclass:: sphinx_runpython.gdot.sphinx_gdot_extension.GDotDirective

‎_doc/api/index.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,13 @@ Extensions
99
.. toctree::
1010
:maxdepth: 1
1111

12+
blocdefs
13+
blocdefs_list
1214
collapse
1315
docassert
1416
epkg
17+
gdot
1518
runpython
16-
blocdefs
17-
blocdefs_list
1819

1920
Helpers
2021
=======

‎_doc/api/runpython.rst‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,6 @@ the output to the documentation, as plain text or even RST format.
88
Usage
99
=====
1010

11-
Location: :class:`RunPythonDirective <sphinx_runpython.runpython.sphinx_runpython_extension.RunPythonDirective>`.
12-
1311
In *conf.py*:
1412

1513
::

‎_doc/conf.py‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,20 +5,22 @@
55

66
extensions = [
77
"sphinx.ext.autodoc",
8-
"sphinx.ext.intersphinx",
9-
"sphinx.ext.todo",
108
"sphinx.ext.coverage",
11-
"sphinx.ext.mathjax",
9+
"sphinx.ext.githubpages",
10+
"sphinx.ext.graphviz",
1211
"sphinx.ext.ifconfig",
12+
"sphinx.ext.intersphinx",
13+
"sphinx.ext.mathjax",
14+
"sphinx.ext.todo",
1315
"sphinx.ext.viewcode",
14-
"sphinx.ext.githubpages",
1516
"sphinx_gallery.gen_gallery",
1617
"matplotlib.sphinxext.plot_directive",
1718
"sphinx_runpython.blocdefs.sphinx_blocref_extension",
1819
"sphinx_runpython.blocdefs.sphinx_exref_extension",
1920
"sphinx_runpython.blocdefs.sphinx_mathdef_extension",
2021
"sphinx_runpython.collapse",
2122
"sphinx_runpython.docassert",
23+
"sphinx_runpython.gdot",
2224
"sphinx_runpython.epkg",
2325
"sphinx_runpython.runpython",
2426
]
@@ -58,9 +60,12 @@
5860

5961
epkg_dictionary = {
6062
"autopep8": "https://pypi.org/project/autopep8/",
61-
"DOT": "https://graphviz.org/doc/info/lang.html",
63+
"dot": "https://en.wikipedia.org/wiki/DOT_(graph_description_language)",
64+
"DOT": "https://en.wikipedia.org/wiki/DOT_(graph_description_language)",
6265
"JIT": "https://en.wikipedia.org/wiki/Just-in-time_compilation",
6366
"git": "https://git-scm.com/",
67+
"Graphviz": "https://graphviz.org/",
68+
"HTML": "https://simple.wikipedia.org/wiki/HTML",
6469
"nested_parse_with_titles": "http://sphinx-doc.org/extdev/markupapi.html?highlight=nested_parse_with_titles",
6570
"numpy": (
6671
"https://www.numpy.org/",
@@ -77,10 +82,13 @@
7782
),
7883
"pandoc": "https://johnmacfarlane.net/pandoc/",
7984
"Pandoc": "https://johnmacfarlane.net/pandoc/",
85+
"PNG": "https://en.wikipedia.org/wiki/PNG",
8086
"python": "https://www.python.org/",
8187
"RST": "https://fr.wikipedia.org/wiki/ReStructuredText",
8288
"sphinx": "https://www.sphinx-doc.org/en/master/",
8389
"sphinx-gallery": "https://github.com/sphinx-gallery/sphinx-gallery",
90+
"SVG": "https://en.wikipedia.org/wiki/SVG",
91+
"viz.js": "https://visjs.org/",
8492
"*py": (
8593
"https://docs.python.org/3/",
8694
("https://docs.python.org/3/library/{0}.html", 1),

‎_unittests/ut_gdot/test_download_helper.py‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
import os
2+
import unittest
3+
from pyquickhelper.pycode import get_temp_folder
4+
from sphinx_runpython.ext_test_case import ExtTestCase
5+
from sphinx_runpython.ext_io_helper import get_url_content_timeout, InternetException
6+
7+
8+
class TestDownloadHelper(ExtTestCase):
9+
def test_download_notimeout(self):
10+
url = "https://raw.githubusercontent.com/sdpython/pyquickhelper/master/src/pyquickhelper/ipythonhelper/magic_parser.py"
11+
content = get_url_content_timeout(url, encoding="utf8")
12+
self.assertIn("MagicCommandParser", content)
13+
self.assertIsInstance(content, str)
14+
15+
def test_download_notimeout_chunk(self):
16+
temp = get_temp_folder(__file__, "temp_download_notimeout_chunk")
17+
url = "https://raw.githubusercontent.com/sdpython/pyquickhelper/master/src/pyquickhelper/ipythonhelper/magic_parser.py"
18+
self.assertRaise(
19+
lambda: get_url_content_timeout(url, encoding="utf8", chunk=100),
20+
InternetException,
21+
)
22+
name = os.path.join(temp, "m.py")
23+
content = get_url_content_timeout(url, encoding="utf8", chunk=100, output=name)
24+
with open(name, "r", encoding="utf-8") as f:
25+
content = f.read()
26+
self.assertIn("MagicCommandParser", content)
27+
self.assertIsInstance(content, str)
28+
self.assertRaise(
29+
lambda: get_url_content_timeout(url, chunk=100), InternetException
30+
)
31+
name = os.path.join(temp, "m2.py")
32+
content = get_url_content_timeout(url, chunk=100, output=name)
33+
with open(name, "r", encoding="utf-8") as f:
34+
content = f.read()
35+
self.assertIn("MagicCommandParser", content)
36+
self.assertIsInstance(content, str)
37+
38+
def test_download_timeout(self):
39+
url = "https://localhost:878777/should_not_exists"
40+
try:
41+
get_url_content_timeout(url, encoding="utf8", timeout=2)
42+
except InternetException:
43+
return
44+
45+
assert False
46+
47+
48+
if __name__ == "__main__":
49+
unittest.main(verbosity=2)

0 commit comments

Comments
 (0)