📝 Generate API docs automatically

cherrypy · Sep 5, 2020 · cb9d3f4 · cb9d3f4
1 parent 6b69862
commit cb9d3f4
Show file tree

Hide file tree

Showing 15 changed files with 20 additions and 263 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -20,12 +20,24 @@
     'sphinx.ext.intersphinx',
     'jaraco.packaging.sphinx',
     'sphinx_tabs.tabs',
+    'sphinxcontrib.apidoc',
     'sphinxcontrib.spelling',
     'scm_tag_titles_ext',
 ]
 
 master_doc = 'index'
 
+apidoc_excluded_paths = []
+apidoc_extra_args = [
+    '--implicit-namespaces',
+    '--private',  # include “_private” modules
+]
+apidoc_module_dir = '../cheroot'
+apidoc_module_first = False
+apidoc_output_dir = 'pkg'
+apidoc_separate_modules = True
+apidoc_toc_file = None
+
 spelling_ignore_acronyms = True
 spelling_ignore_importable_modules = True
 spelling_ignore_pypi_package_names = True
@@ -92,9 +104,6 @@
 # NOTE: consider having a separate ignore file
 # Ref: https://stackoverflow.com/a/30624034/595220
 nitpick_ignore = [
-    ('py:class', 'cheroot.connections.ConnectionManager'),
-    ('py:meth', 'cheroot.connections.ConnectionManager.get_conn'),
-
     ('py:const', 'socket.SO_PEERCRED'),
     ('py:class', '_pyio.BufferedWriter'),
     ('py:class', '_pyio.BufferedReader'),

diff --git a/docs/index.rst b/docs/index.rst
@@ -9,7 +9,11 @@ Welcome to Cheroot documentation!
 
    contribute
    history
-   pkg/*
+
+.. toctree::
+   :caption: Reference
+
+   pkg/modules
 
 
 `Cheroot <https://github.com/cherrypy/cheroot>`_ is the high-performance,

diff --git a/docs/pkg/.gitignore b/docs/pkg/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/docs/pkg/cheroot._compat.rst b/docs/pkg/cheroot._compat.rst
diff --git a/docs/pkg/cheroot.errors.rst b/docs/pkg/cheroot.errors.rst
diff --git a/docs/pkg/cheroot.makefile.rst b/docs/pkg/cheroot.makefile.rst
diff --git a/docs/pkg/cheroot.server.rst b/docs/pkg/cheroot.server.rst
diff --git a/docs/pkg/cheroot.ssl.builtin.rst b/docs/pkg/cheroot.ssl.builtin.rst
diff --git a/docs/pkg/cheroot.ssl.pyopenssl.rst b/docs/pkg/cheroot.ssl.pyopenssl.rst
diff --git a/docs/pkg/cheroot.ssl.rst b/docs/pkg/cheroot.ssl.rst
diff --git a/docs/pkg/cheroot.test.rst b/docs/pkg/cheroot.test.rst
diff --git a/docs/pkg/cheroot.testing.rst b/docs/pkg/cheroot.testing.rst
diff --git a/docs/pkg/cheroot.workers.rst b/docs/pkg/cheroot.workers.rst
diff --git a/docs/pkg/cheroot.wsgi.rst b/docs/pkg/cheroot.wsgi.rst
diff --git a/setup.cfg b/setup.cfg
@@ -82,6 +82,7 @@ docs =
     alabaster
     # `scm_tag_titles_ext` extension dep in docs/
     python-dateutil
+    sphinxcontrib-apidoc>=0.3.0
     sphinxcontrib-spelling>=5.2.0
 
 testing =