Skip to content

Commit 4c48753

Browse files
sdpythonsdpython
committed
first draft
1 parent 849b87a commit 4c48753

File tree

14 files changed

+391
-44
lines changed

14 files changed

+391
-44
lines changed

‎_doc/api/epkg.rst‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
.. _l-sphinx-epkg:
2+
3+
====
4+
epkg
5+
====
6+
7+
Location: :func:`epkg_role <sphinx_runpython.epkg.sphinxext_epkg_extension.epkg_role>`.
8+
9+
In *conf.py*:
10+
11+
::
12+
13+
extensions = [ ...
14+
'pyquickhelper.sphinxext.sphinx_epkg_extension']
15+
16+
epkg_dictionary = {
17+
'pandoc': 'http://johnmacfarlane.net/pandoc/', # 1
18+
'pandas': ('http://pandas.pydata.org/pandas-docs/stable/', # 2
19+
('http://pandas.pydata.org/pandas-docs/stable/generated/pandas.{0}.html', 1)), # 3
20+
}
21+
22+
The variable ``epkg_dictionary`` stores the list of url to display. It can be a simple
23+
string or a list of possibililies with multiple parameters. The three options above can
24+
used like this. The last one allows one parameter separated by ``:``.
25+
26+
.. sidebar:: epkg
27+
28+
::
29+
30+
* Option 1: :epkg:`pandoc`
31+
* Option 2: :epkg:`pandas`,
32+
* Option 3: :epkg:`pandas:DataFrame`
33+
34+
* Option 1: :epkg:`pandoc`
35+
* Option 2: :epkg:`pandas`,
36+
* Option 3: :epkg:`pandas:DataFrame`
37+
38+
The last link is broken before the current file is not python
39+
file but a *rst*. The file extension must be specified.
40+
For some websites, url and functions do not follow the same rule.
41+
A function must be used in this case to handle the mapping.
42+
43+
::
44+
45+
def weird_mapping(input):
46+
# The function receives whatever is between `...`.
47+
...
48+
return anchor, url
49+
50+
This function must be placed at the end or be the only available option.
51+
52+
::
53+
54+
epkg_dictionary = { 'weird_site': weird_mapping }
55+
56+
However, because it is impossible to use a function as a value
57+
in the configuration because :epkg:`*py:pickle` does not handle
58+
this scenario (see `PicklingError on environment when config option
59+
value is a callable <https://github.com/sphinx-doc/sphinx/issues/1424>`_),
60+
``my_custom_links`` needs to be replaced by:
61+
``("module_where_it_is_defined.my_custom_links", None)``.
62+
The role *epkg* will import it based on its name.

‎_doc/api/helpers.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. _l-api-helpers:
2+
3+
=======
4+
helpers
5+
=======
6+
7+
.. autofunction:: sphinx_runpython.helpers.rst2html

‎_doc/api/import_object_helper.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. _l-api-import_object_helper:
2+
3+
====================
4+
import_object_helper
5+
====================
6+
7+
.. autofunction:: sphinx_runpython.import_object_helper.import_any_object

‎_doc/api/index.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,6 @@ API
66
.. toctree::
77
:maxdepth: 1
88

9-
tools
9+
epkg
10+
helpers
11+
import_object_helper

‎_doc/conf.py‎

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
"sphinx_gallery.gen_gallery",
1717
"matplotlib.sphinxext.plot_directive",
1818
"sphinx_runpython.epkg",
19-
"sphinx_runpython.runpython",
19+
# "sphinx_runpython.runpython",
2020
]
2121

2222
templates_path = ["_templates"]
@@ -42,7 +42,6 @@
4242
intersphinx_mapping = {
4343
"matplotlib": ("https://matplotlib.org/", None),
4444
"numpy": ("https://numpy.org/doc/stable", None),
45-
"pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
4645
"python": (f"https://docs.python.org/{sys.version_info.major}", None),
4746
}
4847

@@ -56,8 +55,28 @@
5655
epkg_dictionary = {
5756
"DOT": "https://graphviz.org/doc/info/lang.html",
5857
"JIT": "https://en.wikipedia.org/wiki/Just-in-time_compilation",
59-
"numpy": "https://numpy.org/",
60-
"pyinstrument": "https://github.com/joerick/pyinstrument",
58+
"numpy": (
59+
"https://www.numpy.org/",
60+
("https://docs.scipy.org/doc/numpy/reference/generated/numpy.{0}.html", 1),
61+
("https://docs.scipy.org/doc/numpy/reference/generated/numpy.{0}.{1}.html", 2),
62+
),
63+
"pandas": (
64+
"https://pandas.pydata.org/pandas-docs/stable/",
65+
("https://pandas.pydata.org/pandas-docs/stable/generated/pandas.{0}.html", 1),
66+
(
67+
"https://pandas.pydata.org/pandas-docs/stable/generated/pandas.{0}.{1}.html",
68+
2,
69+
),
70+
),
71+
"pandoc": "https://johnmacfarlane.net/pandoc/",
72+
"Pandoc": "https://johnmacfarlane.net/pandoc/",
6173
"python": "https://www.python.org/",
6274
"sphinx-gallery": "https://github.com/sphinx-gallery/sphinx-gallery",
75+
"*py": (
76+
"https://docs.python.org/3/",
77+
("https://docs.python.org/3/library/{0}.html", 1),
78+
("https://docs.python.org/3/library/{0}.html#{0}.{1}", 2),
79+
("https://docs.python.org/3/library/{0}.html#{0}.{1}.{2}", 3),
80+
),
81+
"*pyf": (("https://docs.python.org/3/library/functions.html#{0}", 1),),
6382
}

‎_doc/examples/plot_profiling.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,11 @@
55
Empty example
66
=============
77
8+
This demonstrates one of the sphinx extension implemented here.
9+
10+
* use of epkg, link to :epkg:`sphinx-gallery`.
11+
812
"""
913
import sphinx_runpython
14+
15+
print(sphinx_runpython.__version__)

‎_doc/index.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,6 @@ sphinx-runpython: (Numpy) Array API for ONNX
2828
.. toctree::
2929
:maxdepth: 2
3030

31-
tutorial/index
3231
api/index
3332
auto_examples/index
3433

‎_doc/tutorial/index.rst‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎_unittests/ut_epkg/test_epkg_extension.py‎

Lines changed: 40 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,15 @@
11
import unittest
22
from sphinx_runpython.ext_test_case import ExtTestCase, ignore_warnings
3+
from sphinx_runpython.epkg.sphinx_epkg_extension import (
4+
epkg_role,
5+
epkg_node,
6+
visit_epkg_node,
7+
depart_epkg_node,
8+
)
39
from pyquickhelper.helpgen import rst2html
410

11+
tives = [("epkg", epkg_role, epkg_node, visit_epkg_node, depart_epkg_node)]
12+
513

614
class TestEpkgExtension(ExtTestCase):
715
@ignore_warnings(PendingDeprecationWarning)
@@ -20,7 +28,7 @@ def test_epkg_module(self):
2028
content,
2129
writer="custom",
2230
keep_warnings=True,
23-
directives=None,
31+
directives=tives,
2432
layout="sphinx",
2533
epkg_dictionary={
2634
"pandas": (
@@ -35,15 +43,15 @@ def test_epkg_module(self):
3543

3644
t1 = "abeforea"
3745
if t1 not in html:
38-
raise Exception(html)
46+
raise AssertionError(html)
3947

4048
t1 = "aftera"
4149
if t1 not in html:
42-
raise Exception(html)
50+
raise AssertionError(html)
4351

4452
t1 = "http://pandas.pydata.org/pandas-docs/stable/generated/"
4553
if t1 not in html:
46-
raise Exception(html)
54+
raise AssertionError(html)
4755

4856
@ignore_warnings(PendingDeprecationWarning)
4957
def test_epkg_module_twice(self):
@@ -63,7 +71,7 @@ def test_epkg_module_twice(self):
6371
content,
6472
writer="custom",
6573
keep_warnings=True,
66-
directives=None,
74+
directives=tives,
6775
layout="sphinx",
6876
epkg_dictionary={
6977
"pandas": "http://pandas.pydata.org/pandas-docs/stable/generated/",
@@ -89,7 +97,7 @@ def test_epkg_sub(self):
8997
content,
9098
writer="custom",
9199
keep_warnings=True,
92-
directives=None,
100+
directives=tives,
93101
layout="sphinx",
94102
epkg_dictionary={
95103
"pandas": (
@@ -105,25 +113,25 @@ def test_epkg_sub(self):
105113

106114
t1 = "abeforea"
107115
if t1 not in html:
108-
raise Exception(html)
116+
raise AssertionError(html)
109117

110118
t1 = "aftera"
111119
if t1 not in html:
112-
raise Exception(html)
120+
raise AssertionError(html)
113121

114122
spl = html.split("abeforea")[-1].split("aftera")[0]
115123

116124
t1 = "`"
117125
if t1 in html:
118-
raise Exception(f"\n**{spl}**\n----\n{html}")
126+
raise AssertionError(f"\n**{spl}**\n----\n{html}")
119127

120128
t1 = 'href="http://www.7-zip.org/"'
121129
if t1 not in html:
122-
raise Exception(html)
130+
raise AssertionError(html)
123131

124132
t1 = 'href="http://pandas.pydata.org/pandas-docs/stable/generated/DataFrame.to_html.html"'
125133
if t1 not in html:
126-
raise Exception(html)
134+
raise AssertionError(html)
127135

128136
@ignore_warnings(PendingDeprecationWarning)
129137
def test_epkg_function(self):
@@ -146,7 +154,7 @@ def pandas_link(input):
146154
content,
147155
writer="custom",
148156
keep_warnings=True,
149-
directives=None,
157+
directives=tives,
150158
layout="sphinx",
151159
epkg_dictionary={
152160
"pandas": (
@@ -163,25 +171,25 @@ def pandas_link(input):
163171

164172
t1 = "abeforea"
165173
if t1 not in html:
166-
raise Exception(html)
174+
raise AssertionError(html)
167175

168176
t1 = "aftera"
169177
if t1 not in html:
170-
raise Exception(html)
178+
raise AssertionError(html)
171179

172180
spl = html.split("abeforea")[-1].split("aftera")[0]
173181

174182
t1 = "`"
175183
if t1 in html:
176-
raise Exception(f"\n**{spl}**\n----\n{html}")
184+
raise AssertionError(f"\n**{spl}**\n----\n{html}")
177185

178186
t1 = 'href="http://www.7-zip.org/"'
179187
if t1 not in html:
180-
raise Exception(html)
188+
raise AssertionError(html)
181189

182190
t1 = 'href="pandas|DataFrame|to_html"'
183191
if t1 not in html:
184-
raise Exception(html)
192+
raise AssertionError(html)
185193

186194
@ignore_warnings(PendingDeprecationWarning)
187195
def test_epkg_class(self):
@@ -205,7 +213,7 @@ def __call__(self, input):
205213
content,
206214
writer="custom",
207215
keep_warnings=True,
208-
directives=None,
216+
directives=tives,
209217
layout="sphinx",
210218
epkg_dictionary={
211219
"pandas": (
@@ -222,25 +230,25 @@ def __call__(self, input):
222230

223231
t1 = "abeforea"
224232
if t1 not in html:
225-
raise Exception(html)
233+
raise AssertionError(html)
226234

227235
t1 = "aftera"
228236
if t1 not in html:
229-
raise Exception(html)
237+
raise AssertionError(html)
230238

231239
spl = html.split("abeforea")[-1].split("aftera")[0]
232240

233241
t1 = "`"
234242
if t1 in html:
235-
raise Exception(f"\n**{spl}**\n----\n{html}")
243+
raise AssertionError(f"\n**{spl}**\n----\n{html}")
236244

237245
t1 = 'href="http://www.7-zip.org/"'
238246
if t1 not in html:
239-
raise Exception(html)
247+
raise AssertionError(html)
240248

241249
t1 = 'href="pandas|DataFrame|to_html"'
242250
if t1 not in html:
243-
raise Exception(html)
251+
raise AssertionError(html)
244252

245253
@ignore_warnings(PendingDeprecationWarning)
246254
def test_epkg_function_string(self):
@@ -260,7 +268,7 @@ def test_epkg_function_string(self):
260268
content,
261269
writer="custom",
262270
keep_warnings=True,
263-
directives=None,
271+
directives=tives,
264272
layout="sphinx",
265273
epkg_dictionary={
266274
"pandas": (
@@ -280,25 +288,25 @@ def test_epkg_function_string(self):
280288

281289
t1 = "abeforea"
282290
if t1 not in html:
283-
raise Exception(html)
291+
raise AssertionError(html)
284292

285293
t1 = "aftera"
286294
if t1 not in html:
287-
raise Exception(html)
295+
raise AssertionError(html)
288296

289297
spl = html.split("abeforea")[-1].split("aftera")[0]
290298

291299
t1 = "`"
292300
if t1 in html:
293-
raise Exception(f"\n**{spl}**\n----\n{html}")
301+
raise AssertionError(f"\n**{spl}**\n----\n{html}")
294302

295303
t1 = 'href="http://www.7-zip.org/"'
296304
if t1 not in html:
297-
raise Exception(html)
305+
raise AssertionError(html)
298306

299307
t1 = 'href="pandas|DataFrame|to_html"'
300308
if t1 not in html:
301-
raise Exception(html)
309+
raise AssertionError(html)
302310

303311
@ignore_warnings(PendingDeprecationWarning)
304312
def test_epkg_function_long_link(self):
@@ -317,17 +325,17 @@ def test_epkg_function_long_link(self):
317325
content,
318326
writer="custom",
319327
keep_warnings=True,
320-
directives=None,
328+
directives=tives,
321329
layout="sphinx",
322330
)
323331

324332
t1 = 'href="http://first.part/secondpart"'
325333
if t1 not in html:
326-
raise Exception(html)
334+
raise AssertionError(html)
327335

328336
t1 = ">one link on two lines</a>"
329337
if t1 not in html:
330-
raise Exception(html)
338+
raise AssertionError(html)
331339

332340

333341
if __name__ == "__main__":

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,4 @@ line-length = 88
1616
max-complexity = 10
1717

1818
[tool.ruff.per-file-ignores]
19-
# "_doc/examples/plot_first_example.py" = ["E402", "F811"]
19+
"sphinx_runpython/epkg/__init__.py" = ["F401"]

0 commit comments

Comments
 (0)