diff --git a/docs/conf.py b/docs/conf.py index 950fbc91..d26ec84e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,6 +21,8 @@ import os import sys +from sphinx.application import ENV_PICKLE_FILENAME + sys.path.insert(0, os.path.abspath('..')) from patroni.version import __version__ @@ -243,13 +245,24 @@ intersphinx_mapping = {'python': ('https://docs.python.org/', None)} # Remove these pages from index, references, toc trees, etc. # If the builder is not 'html' then add the API docs modules index to pages to be removed. exclude_from_builder = { - 'latex': ['modules/modules'], - 'epub': ['modules/modules'], + 'latex': ['modules/'], + 'epub': ['modules/'], } # Internal holding list, anything added here will always be excluded _docs_to_remove = [] +def config_inited(app, config): + """Run during Sphinx `config-inited` phase. + + rtd reuses the environment, and there is no way to customize this behavior. + Thus we remove the saved env. + """ + pickle_file = os.path.join(app.doctreedir, ENV_PICKLE_FILENAME) + if on_rtd and os.path.exists(pickle_file): + os.remove(pickle_file) + + def builder_inited(app): """Run during Sphinx `builder-inited` phase. @@ -263,14 +276,26 @@ def builder_inited(app): _docs_to_remove.extend(exclude_from_builder[app.builder.name]) +def _to_be_removed(doc): + for remove in _docs_to_remove: + if doc.startswith(remove): + return True + return False + + def env_get_outdated(app, env, added, changed, removed): """Run during Sphinx `env-get-outdated` phase. Remove the items listed in `docs_to_remove` from known pages. """ - added.difference_update(_docs_to_remove) - changed.difference_update(_docs_to_remove) - removed.update(_docs_to_remove) + to_remove = set() + for doc in env.found_docs: + if _to_be_removed(doc): + to_remove.add(doc) + added.difference_update(to_remove) + changed.difference_update(to_remove) + removed.update(to_remove) + env.project.docnames.difference_update(to_remove) return [] @@ -282,8 +307,7 @@ def doctree_read(app, doctree): from sphinx import addnodes for toc_tree_node in doctree.traverse(addnodes.toctree): for e in toc_tree_node['entries']: - ref = str(e[1]) - if ref in _docs_to_remove: + if _to_be_removed(str(e[1])): toc_tree_node['entries'].remove(e) @@ -304,6 +328,7 @@ def setup(app): app.add_stylesheet('custom.css') # Run extra steps to remove module docs when running with a non-html builder + app.connect('config-inited', config_inited) app.connect('builder-inited', builder_inited) app.connect('env-get-outdated', env_get_outdated) app.connect('doctree-read', doctree_read) diff --git a/requirements.docs.txt b/requirements.docs.txt index afb47378..7a47ebb2 100644 --- a/requirements.docs.txt +++ b/requirements.docs.txt @@ -2,3 +2,5 @@ sphinx>=4 sphinx_rtd_theme>1 sphinxcontrib-apidoc sphinx-github-style<1.0.3 +psycopg[binary] +psycopg2-binary diff --git a/tox.ini b/tox.ini index 21688937..1731548a 100644 --- a/tox.ini +++ b/tox.ini @@ -180,6 +180,22 @@ allowlist_externals = platform = {[common]platforms} +[testenv:epub-{lin,mac,win}] +description = Build Sphinx documentation in epub format +labels: + docs +deps = + -r requirements.docs.txt + -r requirements.txt +commands = + python -m sphinx -T -b epub -d _build/doctrees -D language=en . epub +allowlist_externals = + true + {env:OPEN_CMD} +platform = + {[common]platforms} +change_dir = docs + [testenv:docs-{lin,mac,win}] description = Build Sphinx documentation in HTML format labels: @@ -187,8 +203,6 @@ labels: deps = -r requirements.docs.txt -r requirements.txt - psycopg[binary] - psycopg2-binary commands = sphinx-build \ -d "{envtmpdir}{/}doctree" docs "{toxworkdir}{/}docs_out" \ @@ -210,8 +224,6 @@ labels: deps = -r requirements.docs.txt -r requirements.txt - psycopg[binary] - psycopg2-binary commands = python -m sphinx -T -E -b latex -d _build/doctrees -D language=en . pdf - latexmk -r pdf/latexmkrc -cd -C pdf/Patroni.tex