From a7e9856b4aee83fb10daea9a8f658a09d306f8ad Mon Sep 17 00:00:00 2001 From: Xavier Dupre Date: Wed, 2 Aug 2023 00:37:35 +0200 Subject: [PATCH 1/9] Adds command faqref --- README.rst | 1 + _doc/api/blocdefs.rst | 37 +++ _doc/api/blocdefs_list.rst | 17 ++ _doc/conf.py | 1 + .../ut_blocdefs/test_faqref_extension.py | 119 +++++++++ .../blocdefs/sphinx_faqref_extension.py | 234 ++++++++++++++++++ sphinx_runpython/process_rst.py | 1 + 7 files changed, 410 insertions(+) create mode 100644 _unittests/ut_blocdefs/test_faqref_extension.py create mode 100644 sphinx_runpython/blocdefs/sphinx_faqref_extension.py diff --git a/README.rst b/README.rst index 5bbeb6c..5c934a5 100644 --- a/README.rst +++ b/README.rst @@ -85,6 +85,7 @@ List of directives * `docassert `_ * `epkg `_ * `exref `_ +* `faqref `_ * `gdot `_ * `mathdef `_ * `runpython `_ diff --git a/_doc/api/blocdefs.rst b/_doc/api/blocdefs.rst index 5c6feb5..c2c0bc5 100644 --- a/_doc/api/blocdefs.rst +++ b/_doc/api/blocdefs.rst @@ -45,6 +45,43 @@ Which gives: A reference can be added to this example :ref:`Example 1 `. The title needs to be recalled. +faqref +====== + +Location: :class:`faqref `. + +In *conf.py*: + +:: + + extensions = [ ... + 'sphinx_runpython.blocdefs.sphinx_faqref_extension'] + + faqref_include_faqrefs = True + +An example: + +:: + + .. faqref:: + :title: How to add an example? + :tag: faq1 + :label: l-this-faq + + This example, a piece of code... + +Which gives: + +.. faqref:: + :title: How to add an example? + :tag: faq1 + :label: l-this-faq + + This example, a piece of code... + +A reference can be added to this example :ref:`Faq 1 `. +The title needs to be recalled. + blocref ======= diff --git a/_doc/api/blocdefs_list.rst b/_doc/api/blocdefs_list.rst index 5ef6ec2..62b609f 100644 --- a/_doc/api/blocdefs_list.rst +++ b/_doc/api/blocdefs_list.rst @@ -22,6 +22,23 @@ Which gives: :tag: example :contents: +faqreflist +========== + +Example: + +:: + + .. faqreflist:: + :tag: faq + :contents: + +Which gives: + +.. faqreflist:: + :tag: faq + :contents: + blocreflist =========== diff --git a/_doc/conf.py b/_doc/conf.py index 931a5e8..e90d91b 100644 --- a/_doc/conf.py +++ b/_doc/conf.py @@ -20,6 +20,7 @@ "sphinx_issues", "sphinx_runpython.blocdefs.sphinx_blocref_extension", "sphinx_runpython.blocdefs.sphinx_exref_extension", + "sphinx_runpython.blocdefs.sphinx_faqref_extension", "sphinx_runpython.blocdefs.sphinx_mathdef_extension", "sphinx_runpython.collapse", "sphinx_runpython.docassert", diff --git a/_unittests/ut_blocdefs/test_faqref_extension.py b/_unittests/ut_blocdefs/test_faqref_extension.py new file mode 100644 index 0000000..5fd3df8 --- /dev/null +++ b/_unittests/ut_blocdefs/test_faqref_extension.py @@ -0,0 +1,119 @@ +import unittest +from sphinx_runpython.process_rst import rst2html +from sphinx_runpython.ext_test_case import ExtTestCase, ignore_warnings + + +class TestFaqRefExtension(ExtTestCase): + @ignore_warnings(PendingDeprecationWarning) + def test_faqref(self): + content = """ + test a directive + ================ + + before + + .. faqref:: + :title: first todo + :tag: bug + :lid: id3 + + this code shoud appear___ + + after + """.replace( + " ", "" + ) + content = content.replace('u"', '"') + + html = rst2html( + content, + writer_name="rst", + ) + + t1 = "this code shoud appear" + if t1 not in html: + raise AssertionError("ISSUE in " + html) + + t1 = "after" + if t1 not in html: + raise AssertionError("ISSUE in " + html) + + t1 = "first todo" + if t1 not in html: + raise AssertionError("ISSUE in " + html) + + @ignore_warnings(PendingDeprecationWarning) + def test_faqreflist(self): + content = """ + test a directive + ================ + + before + + .. faqref:: + :title: first todo + :tag: freg + :lid: id3 + + this code shoud appear___ + + middle + + .. faqreflist:: + :tag: freg + :sort: title + + after + """.replace( + " ", "" + ) + content = content.replace('u"', '"') + + html = rst2html(content, writer_name="rst") + + t1 = "this code shoud appear" + if t1 not in html: + raise AssertionError("ISSUE in " + html) + + t1 = "after" + if t1 not in html: + raise AssertionError("ISSUE in " + html) + + t1 = "first todo" + if t1 not in html: + raise AssertionError("ISSUE in " + html) + + @ignore_warnings(PendingDeprecationWarning) + def test_faqreflist_rst(self): + content = """ + test a directive + ================ + + before + + .. faqref:: + :title: first todo + :tag: freg + :lid: id3 + + this code shoud appear___ + + middle + + .. faqreflist:: + :tag: freg + :sort: title + + after + """.replace( + " ", "" + ) + content = content.replace('u"', '"') + + rst = rst2html(content, writer_name="rst") + + self.assertNotEmpty(rst) + + +if __name__ == "__main__": + unittest.main(verbosity=2) diff --git a/sphinx_runpython/blocdefs/sphinx_faqref_extension.py b/sphinx_runpython/blocdefs/sphinx_faqref_extension.py new file mode 100644 index 0000000..837d73d --- /dev/null +++ b/sphinx_runpython/blocdefs/sphinx_faqref_extension.py @@ -0,0 +1,234 @@ +from docutils import nodes + +import sphinx +from .sphinx_blocref_extension import ( + BlocRef, + process_blocrefs_generic, + BlocRefList, + process_blocref_nodes_generic, +) + + +class faqref_node(nodes.admonition): + """ + Defines ``faqref`` node. + """ + + pass + + +class faqreflist(nodes.General, nodes.Element): + """ + Defines ``faqreflist`` node. + """ + + pass + + +class FaqRef(BlocRef): + """ + A ``faqref`` entry, displayed in the form of an admonition. + It takes the following options: + + * *title*: a title for the bloc + * *tag*: a tag to have several categories of blocs (optional) + * *lid* or *label*: a label to refer to + * *index*: to add an entry to the index (comma separated) + + Example:: + + .. faqref:: + :title: example of a blocref + :label: id-you-can-choose6 + + An example of code: + + :: + + print("mignon") + + Which renders as: + + .. faqref:: + :title: example of a faqref + :tag: dummy_example6 + :label: id-you-can-choose6 + + An example of code: + + :: + + print("mignon") + + All blocs can be displayed in another page by using ``faqreflist``:: + + .. faqreflist:: + :tag: dummy_example6 + :sort: title + + Only blocs tagged as ``dummy_example`` will be inserted here. + The option ``sort`` sorts items by *title*, *number*, *file*. + You also link to it by typing ``:ref:'anchor '`` which gives + something like :ref:`link_to_blocref `. + The link must receive a name. + + .. faqreflist:: + :tag: dummy_example6 + :sort: title + """ + + node_class = faqref_node + name_sphinx = "faqref" + + def run(self): + """ + Calls run from @see cl BlocRef and add defaut tag. + """ + if "tag" not in self.options: + self.options["tag"] = "faq" + return BlocRef.run(self) + + +def process_faqrefs(app, doctree): + """ + Collects all *faqref* in the environment + this is not done in the directive itself because it some transformations + must have already been run, e.g. substitutions. + """ + process_blocrefs_generic(app, doctree, bloc_name="faqref", class_node=faqref_node) + + +class FaqRefList(BlocRefList): + """ + A list of all *faqref* entries, for a specific tag. + + * tag: a tag to filter bloc having this tag + * sort: a way to sort the blocs based on the title, file, number, default: *title* + * contents: add a bullet list with links to added blocs + + Example:: + + .. faqreflist:: + :tag: issue + """ + + name_sphinx = "faqreflist" + node_class = faqreflist + + def run(self): + """ + calls run from @see cl BlocRefList and add default tag if not present + """ + if "tag" not in self.options: + self.options["tag"] = "faq" + return BlocRefList.run(self) + + +def process_faqref_nodes(app, doctree, fromdocname): + """ + process_blocref_nodes + """ + process_blocref_nodes_generic( + app, + doctree, + fromdocname, + class_name="faqref", + entry_name="faqmes", + class_node=faqref_node, + class_node_list=faqreflist, + ) + + +def purge_faqrefs(app, env, docname): + """ + purge_faqrefs + """ + if not hasattr(env, "faqref_all_faqrefs"): + return + env.faqref_all_faqrefs = [ + faqref for faqref in env.faqref_all_faqrefs if faqref["docname"] != docname + ] + + +def merge_faqref(app, env, docnames, other): + """ + merge_faqref + """ + if not hasattr(other, "faqref_all_faqrefs"): + return + if not hasattr(env, "faqref_all_faqrefs"): + env.faqref_all_faqrefs = [] + env.faqref_all_faqrefs.extend(other.faqref_all_faqrefs) + + +def visit_faqref_node(self, node): + """ + visit_faqref_node + """ + self.visit_admonition(node) + + +def depart_faqref_node(self, node): + """ + depart_faqref_node, + see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py. + """ + self.depart_admonition(node) + + +def visit_faqreflist_node(self, node): + """ + visit_faqreflist_node + see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py. + """ + self.visit_admonition(node) + + +def depart_faqreflist_node(self, node): + """ + depart_faqref_node + """ + self.depart_admonition(node) + + +def setup(app): + """ + setup for ``faqref`` (sphinx) + """ + if hasattr(app, "add_mapping"): + app.add_mapping("faqref", faqref_node) + app.add_mapping("faqreflist", faqreflist) + + app.add_config_value("faqref_include_faqrefs", True, "html") + app.add_config_value("faqref_link_only", False, "html") + + app.add_node( + faqreflist, + html=(visit_faqreflist_node, depart_faqreflist_node), + epub=(visit_faqreflist_node, depart_faqreflist_node), + elatex=(visit_faqreflist_node, depart_faqreflist_node), + latex=(visit_faqreflist_node, depart_faqreflist_node), + tex=(visit_faqreflist_node, depart_faqreflist_node), + text=(visit_faqreflist_node, depart_faqreflist_node), + md=(visit_faqreflist_node, depart_faqreflist_node), + rst=(visit_faqreflist_node, depart_faqreflist_node), + ) + app.add_node( + faqref_node, + html=(visit_faqref_node, depart_faqref_node), + epub=(visit_faqref_node, depart_faqref_node), + elatex=(visit_faqref_node, depart_faqref_node), + latex=(visit_faqref_node, depart_faqref_node), + tex=(visit_faqref_node, depart_faqref_node), + text=(visit_faqref_node, depart_faqref_node), + md=(visit_faqref_node, depart_faqref_node), + rst=(visit_faqref_node, depart_faqref_node), + ) + + app.add_directive("faqref", FaqRef) + app.add_directive("faqreflist", FaqRefList) + app.connect("doctree-read", process_faqrefs) + app.connect("doctree-resolved", process_faqref_nodes) + app.connect("env-purge-doc", purge_faqrefs) + app.connect("env-merge-info", merge_faqref) + return {"version": sphinx.__display_version__, "parallel_read_safe": True} diff --git a/sphinx_runpython/process_rst.py b/sphinx_runpython/process_rst.py index e300e41..0689228 100644 --- a/sphinx_runpython/process_rst.py +++ b/sphinx_runpython/process_rst.py @@ -20,6 +20,7 @@ "sphinx_issues", "sphinx_runpython.blocdefs.sphinx_blocref_extension", "sphinx_runpython.blocdefs.sphinx_exref_extension", + "sphinx_runpython.blocdefs.sphinx_faqref_extension", "sphinx_runpython.blocdefs.sphinx_mathdef_extension", "sphinx_runpython.collapse", "sphinx_runpython.docassert", From 336949f08cdc03c4bb9ce9335bfdd6e250b79b8d Mon Sep 17 00:00:00 2001 From: Xavier Dupre Date: Wed, 2 Aug 2023 00:41:46 +0200 Subject: [PATCH 2/9] rst --- CHANGELOGS.rst | 1 + pyproject.toml | 2 ++ 2 files changed, 3 insertions(+) diff --git a/CHANGELOGS.rst b/CHANGELOGS.rst index b22b75d..d53b423 100644 --- a/CHANGELOGS.rst +++ b/CHANGELOGS.rst @@ -4,6 +4,7 @@ Change Logs 0.2.0 +++++ +* :pr:`21`: add sphinx extension faqref * :pr:`17`: add RST writer to output the documentation into pure RST format * :pr:`16`: add command line nb2py to convert notebook to python files * :pr:`11`: add function make_linkcode_resolve diff --git a/pyproject.toml b/pyproject.toml index a7a0c58..f2b58ae 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,6 +8,8 @@ ignore_directives = [ "collapse", "exref", "exreflist", + "faqref", + "faqreflist", "gdot", "image-sg", "mathdef", From 08b1c4cb0ca2d5575e42b8a9b3f138ce144cb894 Mon Sep 17 00:00:00 2001 From: Xavier Dupre Date: Wed, 2 Aug 2023 01:00:02 +0200 Subject: [PATCH 3/9] use black instead of pep8 --- requirements-dev.txt | 1 - sphinx_runpython/process_rst.py | 1 - .../runpython/sphinx_runpython_extension.py | 35 +++++++++---------- 3 files changed, 16 insertions(+), 21 deletions(-) diff --git a/requirements-dev.txt b/requirements-dev.txt index 69da7f6..57821d1 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,4 +1,3 @@ -autopep8 black coverage flake8 diff --git a/sphinx_runpython/process_rst.py b/sphinx_runpython/process_rst.py index 0689228..da9e176 100644 --- a/sphinx_runpython/process_rst.py +++ b/sphinx_runpython/process_rst.py @@ -30,7 +30,6 @@ ] _dummy_epkg_dictionary = { - "autopep8": "https://pypi.org/project/autopep8/", "dot": "https://en.wikipedia.org/wiki/DOT_(graph_description_language)", "DOT": "https://en.wikipedia.org/wiki/DOT_(graph_description_language)", "JIT": "https://en.wikipedia.org/wiki/Just-in-time_compilation", diff --git a/sphinx_runpython/runpython/sphinx_runpython_extension.py b/sphinx_runpython/runpython/sphinx_runpython_extension.py index 1a296a1..7a459b9 100644 --- a/sphinx_runpython/runpython/sphinx_runpython_extension.py +++ b/sphinx_runpython/runpython/sphinx_runpython_extension.py @@ -16,15 +16,14 @@ from ..collapse.sphinx_collapse_extension import collapse_node -def remove_extra_spaces_and_pep8( - filename, apply_pep8=True, aggressive=False, is_string=None -): +def remove_extra_spaces_and_black( + filename: str, apply_black=True, is_string=None +) -> str: """ Removes extra spaces in a filename, replaces the file in place. :param filename: file name or string (but it assumes it is python). - :param apply_pep8: if True, calls :epkg:`autopep8` on the file - :param aggressive: more aggressive + :param apply_black: if True, calls :epkg:`black` on the file :param is_string: force *filename* to be a string :return: number of removed extra spaces """ @@ -110,13 +109,11 @@ def cdiff(lines): if filename is not None: ext = os.path.splitext(filename)[-1] - if ext in (".py",) and apply_pep8: + if ext in (".py",) and apply_black: # delayed import to speed up import of pycode - import autopep8 + from black import format_str, FileMode - options = ["", "-a"] if aggressive else [""] - options.extend(["--ignore=E402,E731"]) - r = autopep8.fix_code("\n".join(lines2), options=autopep8.parse_args(options)) + r = format_str("\n".join(lines2), mode=FileMode()) if len(lines) > 0 and (len(lines2) == 0 or len(lines2) < len(lines) // 2): raise ValueError( # pragma: no cover @@ -195,7 +192,7 @@ def cdiff(lines): if not os.path.exists(filename): raise FileNotFoundError( # pragma: no cover - f"Issue when applying autopep8 with filename: '{filename}'." + f"Issue when applying black with filename: '{filename}'." ) return diff @@ -519,9 +516,8 @@ class RunPythonDirective(Directive): * ``:indent:`` to indent the output * ``:language:``: changes ``::`` into ``.. code-block:: language`` * ``:linenos:`` to show line numbers - * ``:nopep8:`` if present, leaves the code as it is and does - not apply pep8 by default, - see :func:`remove_extra_spaces_and_pep8`. + * ``:noblack:`` if present, leaves the code as it is and does + not apply black by default, * ``:numpy_precision: ``, run ``numpy.set_printoptions(precision=...)``, precision is 3 by default * ``:process:`` run the script in an another process @@ -612,7 +608,7 @@ class RunPythonDirective(Directive): "setsysvar": directives.unchanged, "process": directives.unchanged, "exception": directives.unchanged, - "nopep8": directives.unchanged, + "noblack": directives.unchanged, "warningout": directives.unchanged, "toggle": directives.unchanged, "current": directives.unchanged, @@ -672,7 +668,8 @@ def run(self): and self.options["process"] in bool_set_, "exception": "exception" in self.options and self.options["exception"] in bool_set_, - "nopep8": "nopep8" in self.options and self.options["nopep8"] in bool_set_, + "noblack": "noblack" in self.options + and self.options["noblack"] in bool_set_, "warningout": self.options.get("warningout", "").strip(), "toggle": self.options.get("toggle", "").strip(), "current": "current" in self.options @@ -746,9 +743,9 @@ def run(self): script = "\n".join(content) script_disp = "\n".join(self.content) - if not p["nopep8"]: + if not p["noblack"]: try: - script_disp = remove_extra_spaces_and_pep8(script_disp, is_string=True) + script_disp = remove_extra_spaces_and_black(script_disp, is_string=True) except Exception as e: logger = logging.getLogger("runpython") if "." in docname: @@ -759,7 +756,7 @@ def run(self): f'\n File "{docname}.py", line {1}\n' ) logger.warning( - f"Pep8 ({e}) issue with {docname!r}\n---SCRIPT---\n{script}" + f"Black ({e}) issue with {docname!r}\n---SCRIPT---\n{script}" ) # if an exception is raised, the documentation should report a warning From 9204fca71b8844153ecac0f608c6d74947f8f5de Mon Sep 17 00:00:00 2001 From: Xavier Dupre Date: Wed, 2 Aug 2023 01:07:24 +0200 Subject: [PATCH 4/9] api --- CHANGELOGS.rst | 2 +- _doc/api/runpython.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOGS.rst b/CHANGELOGS.rst index d53b423..baa938f 100644 --- a/CHANGELOGS.rst +++ b/CHANGELOGS.rst @@ -4,7 +4,7 @@ Change Logs 0.2.0 +++++ -* :pr:`21`: add sphinx extension faqref +* :pr:`21`: add sphinx extension faqref, runpython uses black * :pr:`17`: add RST writer to output the documentation into pure RST format * :pr:`16`: add command line nb2py to convert notebook to python files * :pr:`11`: add function make_linkcode_resolve diff --git a/_doc/api/runpython.rst b/_doc/api/runpython.rst index ff565d1..2c36846 100644 --- a/_doc/api/runpython.rst +++ b/_doc/api/runpython.rst @@ -189,7 +189,7 @@ Interesting functions .. autofunction:: sphinx_runpython.runpython.run_cmd -.. autofunction:: sphinx_runpython.runpython.sphinx_runpython_extension.remove_extra_spaces_and_pep8 +.. autofunction:: sphinx_runpython.runpython.sphinx_runpython_extension.remove_extra_spaces_and_black Directive ========= From 5e86b497bb209133786e9943d0e7e2e5fd6a8e70 Mon Sep 17 00:00:00 2001 From: Xavier Dupre Date: Wed, 2 Aug 2023 01:12:33 +0200 Subject: [PATCH 5/9] black --- _doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_doc/conf.py b/_doc/conf.py index e90d91b..b8b451e 100644 --- a/_doc/conf.py +++ b/_doc/conf.py @@ -105,7 +105,7 @@ } epkg_dictionary = { - "autopep8": "https://pypi.org/project/autopep8/", + "black": "https://black.readthedocs.io/en/stable/index.html", "dot": "https://en.wikipedia.org/wiki/DOT_(graph_description_language)", "DOT": "https://en.wikipedia.org/wiki/DOT_(graph_description_language)", "JIT": "https://en.wikipedia.org/wiki/Just-in-time_compilation", From 4d363f029bd7ec3957b99ac0bf9462480dda82d0 Mon Sep 17 00:00:00 2001 From: Xavier Dupre Date: Wed, 2 Aug 2023 01:47:41 +0200 Subject: [PATCH 6/9] doc --- _doc/api/blocdefs.rst | 2 +- sphinx_runpython/blocdefs/sphinx_blocref_extension.py | 10 ++++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/_doc/api/blocdefs.rst b/_doc/api/blocdefs.rst index c2c0bc5..03a0b6b 100644 --- a/_doc/api/blocdefs.rst +++ b/_doc/api/blocdefs.rst @@ -48,7 +48,7 @@ The title needs to be recalled. faqref ====== -Location: :class:`faqref `. +Location: :class:`FaqRef `. In *conf.py*: diff --git a/sphinx_runpython/blocdefs/sphinx_blocref_extension.py b/sphinx_runpython/blocdefs/sphinx_blocref_extension.py index 597ba7d..2a18261 100644 --- a/sphinx_runpython/blocdefs/sphinx_blocref_extension.py +++ b/sphinx_runpython/blocdefs/sphinx_blocref_extension.py @@ -85,10 +85,12 @@ class BlocRef(BaseAdmonition): :sort: title This directive is used to highlight a bloc about - anything @see cl BlocRef, a question @see cl FaqRef, - a magic command @see cl NbRef, an example @see cl ExRef. - It supports option *index* in most of the extensions - so that the documentation can refer to it. + anything :class:`sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef`, + a question :class:`sphinx_runpython.blocdefs.sphinx_faqref_extension.FaqRef`, + an example :class:`sphinx_runpython.blocdefs.sphinx_exref_extension.ExRef`. + It supports option *index* + in most of the extensions so that the documentation + can refer to it. """ node_class = blocref_node From 51937232640dea2ca078b72a85fc2bedbe3dcee1 Mon Sep 17 00:00:00 2001 From: Xavier Dupre Date: Wed, 2 Aug 2023 01:57:16 +0200 Subject: [PATCH 7/9] fix doc --- _doc/api/blocdefs.rst | 12 +++++++++--- sphinx_runpython/blocdefs/sphinx_faqref_extension.py | 7 +++++-- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/_doc/api/blocdefs.rst b/_doc/api/blocdefs.rst index 03a0b6b..e31bfec 100644 --- a/_doc/api/blocdefs.rst +++ b/_doc/api/blocdefs.rst @@ -11,7 +11,7 @@ differs depending on the content. exref ===== -Location: :class:`exref `. +Location: :class:`ExRef `. In *conf.py*: @@ -85,7 +85,7 @@ The title needs to be recalled. blocref ======= -Location: :class:`blocref `. +Location: :class:`BlocRef `. In *conf.py*: @@ -122,7 +122,7 @@ The title needs to be recalled. mathdef ======= -Location: :class:`mathdef `. +Location: :class:`MathDef `. In *conf.py*: @@ -160,7 +160,13 @@ Directives ========== .. autoclass:: sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef + :members: .. autoclass:: sphinx_runpython.blocdefs.sphinx_exref_extension.ExRef + :members: + +.. autoclass:: sphinx_runpython.blocdefs.sphinx_faqref_extension.FaqRef + :members: .. autoclass:: sphinx_runpython.blocdefs.sphinx_mathdef_extension.MathDef + :members: diff --git a/sphinx_runpython/blocdefs/sphinx_faqref_extension.py b/sphinx_runpython/blocdefs/sphinx_faqref_extension.py index 837d73d..c0a6b95 100644 --- a/sphinx_runpython/blocdefs/sphinx_faqref_extension.py +++ b/sphinx_runpython/blocdefs/sphinx_faqref_extension.py @@ -82,7 +82,8 @@ class FaqRef(BlocRef): def run(self): """ - Calls run from @see cl BlocRef and add defaut tag. + Calls run from :class:`sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef` + and add defaut tag. """ if "tag" not in self.options: self.options["tag"] = "faq" @@ -117,7 +118,9 @@ class FaqRefList(BlocRefList): def run(self): """ - calls run from @see cl BlocRefList and add default tag if not present + calls run from + :class:`sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRefList` + and add default tag if not present """ if "tag" not in self.options: self.options["tag"] = "faq" From ea9870ba80d1486d6b889c67cb76c4dba14a3baa Mon Sep 17 00:00:00 2001 From: Xavier Dupre Date: Wed, 2 Aug 2023 02:00:18 +0200 Subject: [PATCH 8/9] doc --- sphinx_runpython/blocdefs/sphinx_faqref_extension.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sphinx_runpython/blocdefs/sphinx_faqref_extension.py b/sphinx_runpython/blocdefs/sphinx_faqref_extension.py index c0a6b95..61afbd7 100644 --- a/sphinx_runpython/blocdefs/sphinx_faqref_extension.py +++ b/sphinx_runpython/blocdefs/sphinx_faqref_extension.py @@ -82,7 +82,8 @@ class FaqRef(BlocRef): def run(self): """ - Calls run from :class:`sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef` + Calls run from + :class:`sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef` and add defaut tag. """ if "tag" not in self.options: From 33eee4eed49e5f55b48e0e49e19c9e5f00e23ce4 Mon Sep 17 00:00:00 2001 From: Xavier Dupre Date: Wed, 2 Aug 2023 02:07:31 +0200 Subject: [PATCH 9/9] doc --- _doc/api/blocdefs.rst | 11 +++++++++++ sphinx_runpython/blocdefs/sphinx_exref_extension.py | 8 ++++---- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/_doc/api/blocdefs.rst b/_doc/api/blocdefs.rst index e31bfec..5d2272d 100644 --- a/_doc/api/blocdefs.rst +++ b/_doc/api/blocdefs.rst @@ -170,3 +170,14 @@ Directives .. autoclass:: sphinx_runpython.blocdefs.sphinx_mathdef_extension.MathDef :members: + +Nodes +===== + +.. autoclass:: sphinx_runpython.blocdefs.sphinx_blocref_extension.blocref_node + +.. autoclass:: sphinx_runpython.blocdefs.sphinx_exref_extension.exref_node + +.. autoclass:: sphinx_runpython.blocdefs.sphinx_faqref_extension.faqref_node + +.. autoclass:: sphinx_runpython.blocdefs.sphinx_mathdef_extension.mathdef_node diff --git a/sphinx_runpython/blocdefs/sphinx_exref_extension.py b/sphinx_runpython/blocdefs/sphinx_exref_extension.py index f03ad38..bd2ca45 100644 --- a/sphinx_runpython/blocdefs/sphinx_exref_extension.py +++ b/sphinx_runpython/blocdefs/sphinx_exref_extension.py @@ -39,7 +39,7 @@ class ExRef(BlocRef): .. exref:: :title: example of a blocref - :label: id-you-can-choose6 + :label: id-you-can-choose7 An example of code: @@ -52,7 +52,7 @@ class ExRef(BlocRef): .. exref:: :title: example of a exref :tag: dummy_example6 - :label: id-you-can-choose6 + :label: id-you-can-choose7 An example of code: @@ -68,8 +68,8 @@ class ExRef(BlocRef): Only blocs tagged as ``dummy_example`` will be inserted here. The option ``sort`` sorts items by *title*, *number*, *file*. - You also link to it by typing ``:ref:'anchor '`` which gives - something like :ref:`link_to_blocref `. + You also link to it by typing ``:ref:'anchor '`` which gives + something like :ref:`link_to_blocref `. The link must receive a name. .. exreflist::