📚 DOCS: Add API documentation (#24)

Author: chrisjsewell

.circleci/config.yml

@@ -23,7 +23,7 @@ jobs:
       - run:
           name: Build docs to store
           command: |
-            sphinx-build -b html docs/ docs/_build/html
+            sphinx-build -nW --keep-going -b html docs/ docs/_build/html
 
       - store_artifacts:
           path: docs/_build/html/

.gitignore

@@ -137,3 +137,5 @@ apidoc/
 __pycache__/
 .ropeproject/
 *.egg-info/
+
+docs/api/

docs/conf.py

@@ -27,7 +27,13 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["myst_nb", "sphinx_copybutton"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "myst_nb",
+    "sphinx_copybutton",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -55,4 +61,48 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
+
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3.7", None),
+}
+
+
+def run_apidoc(app):
+    """ generate apidoc
+
+    See: https://github.com/rtfd/readthedocs.org/issues/1139
+    """
+    import os
+    import shutil
+    import sphinx
+    from sphinx.ext import apidoc
+
+    logger = sphinx.util.logging.getLogger(__name__)
+    logger.info("running apidoc")
+    # get correct paths
+    this_folder = os.path.abspath(os.path.dirname(os.path.realpath(__file__)))
+    api_folder = os.path.join(this_folder, "api")
+    module_path = os.path.normpath(os.path.join(this_folder, "../"))
+    ignore_paths = ["../setup.py", "../conftest.py", "../tests", "../benchmark_samples"]
+    ignore_paths = [
+        os.path.normpath(os.path.join(this_folder, p)) for p in ignore_paths
+    ]
+
+    if os.path.exists(api_folder):
+        shutil.rmtree(api_folder)
+    os.mkdir(api_folder)
+
+    argv = ["-M", "--separate", "-o", api_folder, module_path] + ignore_paths
+
+    apidoc.main(argv)
+
+    # we don't use this
+    if os.path.exists(os.path.join(api_folder, "modules.rst")):
+        os.remove(os.path.join(api_folder, "modules.rst"))
+
+
+def setup(app):
+    """Add functions to the Sphinx setup."""
+    app.connect("builder-inited", run_apidoc)

docs/index.md

@@ -2,8 +2,11 @@
 ```
 
 ```{toctree}
+:maxdepth: 2
+
 using
 architecture
 development
 security
+api/markdown_it
 ```

markdown_it/common/normalize_url.py

@@ -68,7 +68,9 @@ def unescape_normalize_uri(x):
 
 
 def normalizeLink(url):
-    """Normalize destination URLs in links::
+    """Normalize destination URLs in links
+
+    ::
 
         [label]:   destination   'title'
                 ^^^^^^^^^^^
@@ -116,7 +118,9 @@ def unescape_unquote(x):
 
 
 def normalizeLinkText(link):
-    """Normalize autolink content::
+    """Normalize autolink content
+
+    ::
 
         <destination>
          ~~~~~~~~~~~

markdown_it/common/utils.py

@@ -114,12 +114,12 @@ def fromCodePoint(c):
 
 
 def replaceEntityPattern(match, name):
-    """
+    """Convert HTML entity patterns
+
     ::
-        In [2]: from markdown_it import MarkdownIt
-           ...: md = MarkdownIt()
-           ...: md.render("![](https://www.google.com)")
-        Out[2]: '<p><img src="https%3A//www.google.com" alt=""></p>\n'
+
+        https://www.google.com -> https%3A//www.google.com
+
     """
     code = 0
 
@@ -275,12 +275,15 @@ def isPunctChar(ch):
 def isMdAsciiPunct(ch: str):
     """Markdown ASCII punctuation characters.
 
-  !, ", #, $, %, &, ', (, ), *, +, ,, -, ., /, :, ;, <, =, >, ?, @, [, \\, ], ^, _, `, {, |, }, or ~
-  http://spec.commonmark.org/0.15/#ascii-punctuation-character
+    ::
 
-  Don't confuse with unicode punctuation !!! It lacks some chars in ascii range.
+        !, ", #, $, %, &, ', (, ), *, +, ,, -, ., /, :, ;, <, =, >, ?, @, [, \\, ], ^, _, `, {, |, }, or ~
 
-  """
+    See http://spec.commonmark.org/0.15/#ascii-punctuation-character
+
+    Don't confuse with unicode punctuation !!! It lacks some chars in ascii range.
+
+    """  # noqa: E501
     return ch in MD_ASCII_PUNCT
 
 

markdown_it/renderer.py

@@ -15,32 +15,30 @@ class Renderer
 class RendererHTML:
     """Contains render rules for tokens. Can be updated and extended.
 
-    ##### Example
+    Example:
 
     Each rule is called as independent static function with fixed signature:
 
-    ```python
-    class Renderer:
-        def token_type_name(self, tokens, idx, options, env) {
-            # ...
-            return renderedHTML
-    ```
+    ::
 
-    example:
+        class Renderer:
+            def token_type_name(self, tokens, idx, options, env) {
+                # ...
+                return renderedHTML
 
-    ```python
-    class CustomRenderer(RendererHTML):
-        def strong_open(self, tokens, idx, options, env):
-            return '<b>'
-        def strong_close(self, tokens, idx, options, env):
-            return '</b>'
+    ::
 
-    md = MarkdownIt(renderer=CustomRenderer)
+        class CustomRenderer(RendererHTML):
+            def strong_open(self, tokens, idx, options, env):
+                return '<b>'
+            def strong_close(self, tokens, idx, options, env):
+                return '</b>'
 
-    result = md.render(...)
-    ```
+        md = MarkdownIt(renderer=CustomRenderer)
 
-    See [source code](https://github.com/markdown-it/markdown-it/blob/master/lib/renderer.js)
+        result = md.render(...)
+
+    See https://github.com/markdown-it/markdown-it/blob/master/lib/renderer.js
     for more details and examples.
     """
 

markdown_it/rules_inline/text_collapse.py

@@ -6,7 +6,7 @@ def text_collapse(state: StateInline, *args):
     Clean up tokens after emphasis and strikethrough postprocessing:
     merge adjacent text nodes into one and re-calculate all token levels
 
-    This is necessary because initially emphasis delimiter markers (*, _, ~)
+    This is necessary because initially emphasis delimiter markers (``*, _, ~``)
     are treated as their own separate text tokens. Then emphasis rule either
     leaves them as text (needed to merge with adjacent text) or turns them
     into opening/closing tags (which messes up levels inside).

markdown_it/token.py

@@ -87,11 +87,11 @@ def as_dict(self, children=True, filter=None, dict_factory=dict):
         """Return the token as a dict.
 
         :param bool children: Also convert children to dicts
-        :param callable filter: A callable whose return code determines whether an
+        :param filter: A callable whose return code determines whether an
             attribute or element is included (``True``) or dropped (``False``).  Is
             called with the `attr.Attribute` as the first argument and the
             value as the second argument.
-        :param callable dict_factory: A callable to produce dictionaries from.  For
+        :param dict_factory: A callable to produce dictionaries from.  For
             example, to produce ordered dictionaries instead of normal Python
             dictionaries, pass in ``collections.OrderedDict``.