Add ReadTheDocs (#2)

.circleci/config.yml

@@ -0,0 +1,38 @@
+version: 2
+jobs:
+  build_docs:
+    docker:
+      - image: circleci/python:3.6-stretch
+    steps:
+      # Get our data and merge with upstream
+      - run: sudo apt-get update
+      - checkout
+
+      - restore_cache:
+          keys:
+            - cache-pip
+      - run: |
+          pip install --user -e .[rtd]
+          pip install -r docs/requirements.txt
+      - save_cache:
+          key: cache-pip
+          paths:
+            - ~/.cache/pip
+
+      # Build the docs
+      - run:
+          name: Build docs to store
+          command: |
+            cd docs
+            make html
+
+      - store_artifacts:
+          path: docs/_build/html/
+          destination: html-strict
+
+
+workflows:
+  version: 2
+  default:
+    jobs:
+      - build_docs

.readthedocs.yml

@@ -0,0 +1,10 @@
+version: 2
+
+python:
+  version: 3
+  install:
+      - method: pip
+        path: .
+        extra_requirements:
+          - rtd
+      - requirements: docs/requirements.txt

README.md

@@ -6,7 +6,7 @@
 [![PyPI][pypi-badge]][pypi-link]
 [![Conda][conda-badge]][conda-link]
 
-This is a version of [mistletoe] maintained by the Excutable Book Project (EBP). It tracks the `myst` branch of [ExecutableBookProject/mistletoe](https://github.com/ExecutableBookProject/mistletoe)
+This is a version of [mistletoe] maintained by the [Excutable Book Project (EBP)][ebp-link]. It tracks the `myst` branch of [ExecutableBookProject/mistletoe](https://github.com/ExecutableBookProject/mistletoe)
 which eventually, it is hoped, will be merged into mistletoe itself.
 
 mistletoe is a Markdown parser in pure Python,
@@ -35,9 +35,10 @@ deployed release that can be utilised by EBP. Here is a working list of 'up-stre
 - Improve rendering logic: Currently, there is no concept of recursive walk-throughs or 'visitor' patterns in the Misteltoe `BaseRenderer`, which is a better method for rendering tree like structures (as used by docutils/panflute). Also, the current token instantiating (within context managers) needs improvement (see [miyuchina/mistletoe#56](https://github.com/miyuchina/mistletoe/issues/56)).
 
 [mistletoe]: https://github.com/miyuchina/mistletoe
+[ebp-link]: https://github.com/ExecutableBookProject
 [travis-badge]: https://travis-ci.org/ExecutableBookProject/mistletoe-ebp.svg?branch=master
 [travis-link]: https://travis-ci.org/ExecutableBookProject/mistletoe-ebp
-[coveralls-badge]: https://coveralls.io/repos/github/ExecutableBookProject/mistletoe-ebp/badge.svg?branch=develop
+[coveralls-badge]: https://coveralls.io/repos/github/ExecutableBookProject/mistletoe-ebp/badge.svg?branch=master
 [coveralls-link]: https://coveralls.io/github/ExecutableBookProject/mistletoe-ebp?branch=master
 [black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
 [pypi-badge]: https://img.shields.io/pypi/v/mistletoe-ebp.svg

docs/.gitignore

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

docs/Makefile

@@ -0,0 +1,27 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# raise warnings to errors
+html-strict:
+	@$(SPHINXBUILD) -b html -nW --keep-going "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -r $(BUILDDIR)

docs/conf.py

@@ -0,0 +1,108 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "mistletoe"
+copyright = "2020, Executable Book Project"
+author = "Executable Book Project"
+
+master_doc = "index"
+
+# -- General configuration ---------------------------------------------------
+
+# 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", "sphinx.ext.autodoc", "sphinx.ext.intersphinx"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "pandas_sphinx_theme"
+html_logo = "_static/logo.svg"
+
+# 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"]
+
+
+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", "../test", "../contrib"]
+    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 = []
+
+
+def setup(app):
+    """Add functions to the Sphinx setup."""
+    # TODO run apidoc
+    # app.connect("builder-inited", run_apidoc)