Sphinx updates

whisk-ml · May 13, 2020 · 8dc7a2b · 8dc7a2b
2 parents ee195ae + fa5774f
commit 8dc7a2b
Show file tree

Hide file tree

Showing 15 changed files with 32 additions and 204 deletions.
diff --git a/.gitignore b/.gitignore
@@ -64,6 +64,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/modules.rst
+docs/whisk*
 
 # PyBuilder
 target/

diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,16 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+  install:
+    - requirements: docs/requirements.txt
diff --git a/Makefile b/Makefile
@@ -65,7 +65,6 @@ coverage: ## check code coverage quickly with the default Python
 docs: ## generate Sphinx HTML documentation, including API docs
 	rm -f docs/whisk.rst
 	rm -f docs/modules.rst
-	sphinx-apidoc -o docs/ whisk
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
 	$(BROWSER) docs/_build/html/index.html

diff --git a/docs/authors.rst b/docs/authors.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -33,7 +33,10 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'recommonmark']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'recommonmark', 'autoapi.extension']
+
+autoapi_dirs = ['../whisk']
+autoapi_ignore = ['*/template/*']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -85,7 +88,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a
 # theme further.  For a list of options available for each theme, see the
@@ -160,7 +163,6 @@
      'Miscellaneous'),
 ]
 
-
 # app setup hook
 # see https://github.com/readthedocs/recommonmark/blob/master/docs/conf.py#L293
 def setup(app):

diff --git a/docs/index_old.rst b/docs/index_old.rst
@@ -5,12 +5,10 @@ Welcome to whisk's documentation!
    :maxdepth: 2
    :caption: Contents:
 
-   readme
    installation
    usage
    modules
    contributing
-   authors
    history
 
 Indices and tables

diff --git a/docs/modules.rst b/docs/modules.rst
diff --git a/docs/readme.md b/docs/readme.md
@@ -0,0 +1 @@
+.. include:: ../README.md
diff --git a/docs/readme.rst b/docs/readme.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,6 @@
+# Dependencies required for building docs
+# conf.py calls import whisk, which will fail without these.
+Click>=7.0
+cookiecutter>=1.7.2
+boto3
+sphinx-autoapi
diff --git a/docs/whisk.cli.commands.project.rst b/docs/whisk.cli.commands.project.rst
diff --git a/docs/whisk.cli.commands.rst b/docs/whisk.cli.commands.rst
diff --git a/docs/whisk.cli.rst b/docs/whisk.cli.rst
diff --git a/docs/whisk.rst b/docs/whisk.rst
diff --git a/requirements_dev.txt b/requirements_dev.txt
@@ -12,3 +12,5 @@ pytest==4.6.5
 pytest-runner==5.1
 check-manifest
 recommonmark # Markdown in sphinx - https://www.sphinx-doc.org/en/master/usage/markdown.html
+sphinx_rtd_theme
+sphinx-autoapi