Merge pull request #80 from stefmolin/gh-docs-updates [skip-ci]

Add post_build.py file for handling moving versioned docs automatically.

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

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)

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}.')