Adds command faqref, runpython uses black

CHANGELOGS.rst

@@ -4,6 +4,7 @@ Change Logs
 0.2.0
 +++++
 
+* :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

README.rst

@@ -85,6 +85,7 @@ List of directives
 * `docassert <https://sdpython.github.io/doc/sphinx-runpython/dev/api/docassert.html>`_
 * `epkg <https://sdpython.github.io/doc/sphinx-runpython/dev/api/epkg.html>`_
 * `exref <https://sdpython.github.io/doc/sphinx-runpython/dev/api/blocdefs.html>`_
+* `faqref <https://sdpython.github.io/doc/sphinx-runpython/dev/api/blocdefs.html>`_
 * `gdot <https://sdpython.github.io/doc/sphinx-runpython/dev/api/gdot.html>`_
 * `mathdef <https://sdpython.github.io/doc/sphinx-runpython/dev/api/blocdefs.html>`_
 * `runpython <https://sdpython.github.io/doc/sphinx-runpython/dev/api/runpython.html>`_

_doc/api/blocdefs.rst

@@ -11,7 +11,7 @@ differs depending on the content.
 exref
 =====
 
-Location: :class:`exref <sphinx_runpython.blocdefs.sphinx_exref_extension.ExRef>`.
+Location: :class:`ExRef <sphinx_runpython.blocdefs.sphinx_exref_extension.ExRef>`.
 
 In *conf.py*:
 
@@ -45,10 +45,47 @@ Which gives:
 A reference can be added to this example :ref:`Example 1 <l-this-example>`.
 The title needs to be recalled.
 
+faqref
+======
+
+Location: :class:`FaqRef <sphinx_runpython.blocdefs.sphinx_faqref_extension.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 <l-this-faq>`.
+The title needs to be recalled.
+
 blocref
 =======
 
-Location: :class:`blocref <sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef>`.
+Location: :class:`BlocRef <sphinx_runpython.blocdefs.sphinx_blocref_extension.BlocRef>`.
 
 In *conf.py*:
 
@@ -85,7 +122,7 @@ The title needs to be recalled.
 mathdef
 =======
 
-Location: :class:`mathdef <sphinx_runpython.blocdefs.sphinx_mathdef_extension.MathDef>`.
+Location: :class:`MathDef <sphinx_runpython.blocdefs.sphinx_mathdef_extension.MathDef>`.
 
 In *conf.py*:
 
@@ -123,7 +160,24 @@ 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:
+
+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

_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
 ===========
 

_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
 =========

_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",
@@ -104,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",

_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)

pyproject.toml

@@ -8,6 +8,8 @@ ignore_directives = [
     "collapse",
     "exref",
     "exreflist",
+    "faqref",
+    "faqreflist",
     "gdot",
     "image-sg",
     "mathdef",

requirements-dev.txt

@@ -1,4 +1,3 @@
-autopep8
 black
 coverage
 flake8

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

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 <id-you-can-choose6>'`` which gives
-    something like :ref:`link_to_blocref <id-you-can-choose6>`.
+    You also link to it by typing ``:ref:'anchor <id-you-can-choose7>'`` which gives
+    something like :ref:`link_to_blocref <id-you-can-choose7>`.
     The link must receive a name.
 
     .. exreflist::