diff --git a/docs/Makefile b/docs/Makefile index 368c00f1..f5319e42 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,7 +3,7 @@ # You can set these variables from the command line. SPHINXOPTS = -SPHINXBUILD = sphinx-build +SPHINXBUILD = python3 -m sphinx PAPER = BUILDDIR = _build/_tmp @@ -37,7 +37,8 @@ clean: -rm -rf `dirname $(BUILDDIR)`/html/*/ $(BUILDDIR) html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR) + python3 post_build.py dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml diff --git a/docs/conf.py b/docs/conf.py index 51b7cbb0..18b3d799 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,11 +7,8 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information import datetime as dt -import glob -import shutil -from pathlib import Path -from packaging.version import parse as parse_version +from post_build import determine_versions import data_morph @@ -20,32 +17,7 @@ copyright = f'2023{f"-{current_year}" if current_year != 2023 else ""}, Stefanie Molin' author = 'Stefanie Molin' release = data_morph.__version__ - -# information on where temporary and permanent files will go -build_html_dir = Path('_build') / 'html' -tmp_build = Path('_build') / '_tmp' / 'html' - -# for determining stable/dev/etc. -last_minor_release = sorted( - [ - parse_version(Path(dir).name) - for dir in glob.glob(f'{build_html_dir}/[0-9].[0-9]/') - ] - or [parse_version('0.0')] -)[-1] -docs_version = parse_version(release) -docs_version_group = parse_version(f'{docs_version.major}.{docs_version.minor}') - -if docs_version.is_devrelease: - version_match = 'dev' -elif docs_version_group >= last_minor_release: - version_match = 'stable' -else: - version_match = f'{docs_version.major}.{docs_version.minor}' - -# clean up the old version -if (old_build := build_html_dir / version_match).exists(): - shutil.rmtree(old_build) +version_match, _ = determine_versions() # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -159,21 +131,6 @@ def docstring_strip(app, what, name, obj, options, lines): lines[0] = ' '.join(extended_summary) -def stable_version_sync(app, exception): - # copy the build to a permanent folder (can't delete here bc it raises an exception) - build = build_html_dir / version_match - shutil.copytree(tmp_build, build, dirs_exist_ok=True) - - if version_match == 'stable': - shutil.copytree( - build, - build_html_dir / str(docs_version_group), - dirs_exist_ok=True, - ) - print(f'Build finished. The HTML pages are in {build}.') - - def setup(app): app.connect('autodoc-skip-member', skip) app.connect('autodoc-process-docstring', docstring_strip) - app.connect('build-finished', stable_version_sync) diff --git a/docs/post_build.py b/docs/post_build.py new file mode 100644 index 00000000..864ab1b4 --- /dev/null +++ b/docs/post_build.py @@ -0,0 +1,53 @@ +"""Maintains the stable docs on the latest version; groups others together.""" + +import glob +import shutil +from pathlib import Path + +from packaging.version import parse as parse_version + +import data_morph + +# information on where temporary and permanent files will go +build_html_dir = Path('_build') / 'html' +tmp_build = Path('_build') / '_tmp' + + +def determine_versions(): + """Determine stable/dev/etc. and docs version number.""" + last_minor_release = sorted( + [ + parse_version(Path(dir).name) + for dir in glob.glob(f'{build_html_dir}/[0-9].[0-9]/') + ] + or [parse_version('0.0')] + )[-1] + docs_version = parse_version(data_morph.__version__) + docs_version_group = parse_version(f'{docs_version.major}.{docs_version.minor}') + + if docs_version.is_devrelease: + version_match = 'dev' + elif docs_version_group >= last_minor_release: + version_match = 'stable' + else: + version_match = f'{docs_version.major}.{docs_version.minor}' + return version_match, docs_version_group + + +if __name__ == '__main__': + version_match, docs_version_group = determine_versions() + + # clean up the old version + if (old_build := build_html_dir / version_match).exists(): + shutil.rmtree(old_build) + + build = build_html_dir / version_match + shutil.move(tmp_build, build) + + if version_match == 'stable': + shutil.copytree( + build, + build_html_dir / str(docs_version_group), + dirs_exist_ok=True, + ) + print(f'Build finished. The HTML pages are in {build}.')