From 4e23e54984abec3f4427e039fd33f0f3d158c891 Mon Sep 17 00:00:00 2001 From: Stephen Herbein Date: Tue, 18 May 2021 11:37:50 -0700 Subject: [PATCH 1/2] docs: run autodoc as part of normal sphinx build Problem: when the documentation is built by ReadTheDocs with Sphinx, they (RTD) do not run autodoc first, resulting in a mostly empty doc site. Solution: follow the workaround prescribed in https://github.com/readthedocs/readthedocs.org/issues/1139 and add code to the conf.py to run autodoc as part of the normal sphinx build process --- docs/conf.py | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 5b3c6c4d..3ac8b388 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,6 +4,7 @@ import sys import sphinx_rtd_theme +from sphinx.ext.apidoc import main needs_sphinx = '1.6' @@ -34,7 +35,8 @@ autodoc_typehints = "description" -src_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), '../src')) +script_dir = os.path.normpath(os.path.dirname(__file__)) +src_dir = os.path.abspath(os.path.join(script_dir, '../src')) print(src_dir + "/") @@ -42,7 +44,22 @@ import psi - intersphinx_mapping = { 'python': ('https://docs.python.org/3', None), } + +# -- Setup for Sphinx API Docs ----------------------------------------------- + +# Workaround since sphinx does not automatically run apidoc before a build +# Copied from https://github.com/readthedocs/readthedocs.org/issues/1139 + +# run api doc +def run_apidoc(_): + output_path = os.path.join(script_dir, '.generated') + print(f"OUTPUT PATH = {output_path}") + #exclusions = [os.path.join(src_dir, 'setup.py'),] + main(['-f', '-o', output_path, src_dir]) + +# launch setup +def setup(app): + app.connect('builder-inited', run_apidoc) \ No newline at end of file From cb01bf32a8997a1e946674c8a7ca6adabdb176c6 Mon Sep 17 00:00:00 2001 From: Stephen Herbein Date: Tue, 18 May 2021 11:39:19 -0700 Subject: [PATCH 2/2] makefile: remove explicit apidoc targets and gen Problem: Sphinx now automatically runs the apidoc as part of the normal build process, making the explicit running of it via make redundant Solution: simplify the makefile a bit and just run the normal sphinx-build process, letting it handle apidoc generation --- Makefile | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/Makefile b/Makefile index bdbbfe7f..0e3b4f87 100644 --- a/Makefile +++ b/Makefile @@ -19,20 +19,9 @@ stylecheck: .PHONY: checks checks: typecheck stylecheck - -.PHONY: genautodocs -genautodocs: - rm -rf docs/.generated - mkdir docs/.generated - sphinx-apidoc -f -o docs/.generated src/ - - .PHONY: docs -docs: genautodocs docs-noauto - - -.PHONY: docs-noauto -docs-noauto: +docs: + rm -rf docs/.generated sphinx-build -W -b html docs docs/.build/ .PHONY: style