Merge 8dd40eb into c6a19fd

docs/.gitignore

@@ -0,0 +1 @@
+api/

docs/conf.py

@@ -28,7 +28,12 @@
 # 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_parser", "sphinxcontrib.bibtex"]
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinxcontrib.bibtex",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -51,3 +56,75 @@
 # 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"]
+
+
+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"]
+    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"))
+
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3.7", None)}
+
+autodoc_default_options = {
+    "show-inheritance": True,
+    "special-members": "__init__, __enter__, __exit__",
+    "members": True,
+    # 'exclude-members': '',
+    "undoc-members": True,
+    # 'inherited-members': True
+}
+autodoc_member_order = "bysource"
+
+nitpick_ignore = [
+    ("py:class", "mistletoe.ast_renderer.ASTRenderer"),
+    ("py:class", "mistletoe.block_token.BlockToken"),
+    ("py:class", "mistletoe.block_token.BlockCode"),
+    ("py:class", "mistletoe.block_token.Heading"),
+    ("py:class", "mistletoe.block_token.Quote"),
+    ("py:class", "mistletoe.block_token.CodeFence"),
+    ("py:class", "mistletoe.block_token.Document"),
+    ("py:class", "mistletoe.block_token.List"),
+    ("py:class", "mistletoe.block_token.ListItem"),
+    ("py:class", "mistletoe.block_token.Table"),
+    ("py:class", "mistletoe.block_token.Footnote"),
+    ("py:class", "mistletoe.block_token.Paragraph"),
+    ("py:class", "mistletoe.base_renderer.BaseRenderer"),
+    ("py:class", "mistletoe.html_renderer.HTMLRenderer"),
+    ("py:class", "mistletoe.span_token.SpanToken"),
+    ("py:class", "mistletoe.span_token.InlineCode"),
+    ("py:class", "docutils.parsers.Parser"),
+]
+
+
+def setup(app):
+    """Add functions to the Sphinx setup."""
+    app.connect("builder-inited", run_apidoc)

docs/index.md

@@ -54,4 +54,5 @@ caption: Contents
 using/index.md
 examples/index.md
 develop/index.md
+package_api.md
 ```

docs/package_api.md

@@ -0,0 +1,7 @@
+# Package API
+
+```{toctree}
+:maxdepth: 3
+
+api/myst_parser.md
+```

myst_parser/docutils_renderer.py

@@ -31,7 +31,7 @@
 class DocutilsRenderer(BaseRenderer):
     """A mistletoe renderer to populate (in-place) a `docutils.document` AST.
 
-    Note this renderer has no dependencies in sphinx.
+    Note this renderer has no dependencies on Sphinx.
     """
 
     def __init__(
@@ -42,15 +42,10 @@ def __init__(
     ):
         """Initialise the renderer.
 
-        Parameters
-        ----------
-        document : docutils.nodes.document
-            The document to populate (or create a new one if None)
-        current_node : docutils.nodes.Element
-            The root node from which to begin populating (default is document)
-            (should be an ancestor of document)
-        config : dict
-            contains configuration specific to the rendering process
+        :param document: The document to populate (or create a new one if None)
+        :param current_node: The root node from which to begin populating
+            (default is document, or should be an ancestor of document)
+        :param config: contains configuration specific to the rendering process
 
         """
         self.config = config or {}