Initial stab at moving the docs to a seperate build process

.github/workflows/sage_test.yml

@@ -47,3 +47,8 @@ jobs:
 
       - name: Do the tests
         run: sage -python -m snappy.test
+
+      - name: Build docs
+        run: |
+          cd doc_src
+          make html

.github/workflows/wheels.yml

@@ -9,33 +9,37 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-20.04, macos-11, windows-2019]
+        os: [macos-latest]
+        # os: [ubuntu-22.04, macos-13, macos-latest, windows-2019]
 
     steps:
       - uses: actions/checkout@v3
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v2.17
+        uses: pypa/cibuildwheel@v2.19
         env:
           # Skip Python 32 bit Linux, and PyPy
+          CIBW_BUILD: "cp312-*"
           CIBW_SKIP: "*-manylinux_i686 *musllinux* pp*"
           CIBW_BEFORE_ALL_LINUX: yum install -y tk mesa-libGLU-devel
           CIBW_BEFORE_BUILD: >
-            pip install cython FXrays low_index sphinx sphinx_rtd_theme &&
+            pip install cython FXrays low_index &&
             pip install --pre --extra-index-url https://test.pypi.org/simple cypari &&
             pip install git+https://github.com/3-manifolds/PLink &&
             pip install git+https://github.com/3-manifolds/snappy_manifolds &&
             pip install git+https://github.com/3-manifolds/Spherogram
           CIBW_BEFORE_TEST: >
-            pip install cython low_index &&
+            pip install cython low_index sphinx sphinx_rtd_theme &&
             pip install --pre --extra-index-url https://test.pypi.org/simple cypari &&
             pip install git+https://github.com/3-manifolds/PLink &&
             pip install git+https://github.com/3-manifolds/snappy_manifolds &&
             pip install git+https://github.com/3-manifolds/Spherogram
           CIBW_REPAIR_WHEEL_COMMAND_LINUX: auditwheel repair --strip -w {dest_dir} {wheel}
-          CIBW_TEST_COMMAND: python -m snappy.test --skip-modern-opengl
+          CIBW_TEST_COMMAND: >
+            cd doc_src && make html
+            python -m snappy.test --skip-modern-opengl
 
       - uses: actions/upload-artifact@v3
         with:
           name: snappy_all_wheels
-          path: ./wheelhouse/*.whl
+          path: ./wheelhouse/*.whl ./doc_src/_build/snappy_doc.zip

doc_src/Makefile

@@ -1,96 +1,23 @@
 # Makefile for Sphinx documentation
-#
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-PAPER         =
-INSTALLDIR = ../snappy/doc
 
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest install
+.PHONY: clean html 
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html      to make standalone HTML files"
-	@echo "  dirhtml   to make HTML files named index.html in directories"
-	@echo "  pickle    to make pickle files"
-	@echo "  json      to make JSON files"
-	@echo "  htmlhelp  to make HTML files and a HTML help project"
-	@echo "  qthelp    to make HTML files and a qthelp project"
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  changes   to make an overview of all changed/added/deprecated items"
-	@echo "  linkcheck to check all external links for integrity"
-	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
-	@echo "  install   to install the documentation in the snappy module directory"
+	@echo "  clean     to delete all generated files in _build"
 
 clean:
 	-rm -rf _build/*
 
+# sphinx options:
+#   -E forces it to rebuild the docs from scratch every time.
+#   -d keeps the intermediate doctree files out the html directory.
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
-	@echo
-	@echo "Build finished. The HTML pages are in _build/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in _build/dirhtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in _build/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in _build/qthelp, like this:"
-	@echo "# qcollectiongenerator _build/qthelp/PLink.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile _build/qthelp/PLink.qhc"
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in _build/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
+	$(SPHINXBUILD) -b html -E -d _build/doctrees . _build/doc
+	cd _build && zip -r snappy_doc.zip doc
 	@echo
-	@echo "The overview file is in _build/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in _build/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in _build/doctest/output.txt."
-
-
-install:   clean html
-	rm -rf $(INSTALLDIR)
-	mv _build/html $(INSTALLDIR)
-	@echo "Installed docs in snappy directory"
+	@echo "Build finished. The HTML pages are in _build/doc and"
+	@echo "zipfile is _build/snappy_doc.zip."

doc_src/add_doc_to_wheel.py

@@ -0,0 +1,41 @@
+#! /usr/bin/env python3
+
+"""
+Adds doc directory to exisiting wheel
+"""
+
+import subprocess
+import sys
+import os
+import tempfile
+import glob
+import shutil
+
+doc_zipfile = os.path.abspath(sys.argv[1])
+wheel_path = os.path.abspath(sys.argv[2])
+
+if not (doc_zipfile.endswith('.zip') and wheel_path.endswith('.whl')):
+    raise ValueError('Usage: add_doc_to_wheel docs.zip snappy.whl')
+
+python = sys.executable
+tmp_dir = tempfile.mkdtemp()
+subprocess.check_call([python, '-m', 'wheel', 'unpack', '--dest', tmp_dir, wheel_path])
+pkg, version = os.path.basename(wheel_path).split('-')[:2]
+wheel_dir = os.path.join(tmp_dir, pkg + '-' + version)
+target = os.path.join(wheel_dir, pkg)
+target_doc_dir = os.path.join(target, 'doc')
+if os.path.exists(target_doc_dir):
+    print('Deleting existing docs...')
+    shutil.rmtree(target_doc_dir)
+print('Unpacking docs..')
+subprocess.check_call(['unzip', '-q', doc_zipfile, '-d', target])
+subprocess.check_call([python, '-m', 'wheel', 'pack', '--dest', tmp_dir, wheel_dir])
+new_whl = glob.glob(os.path.join(tmp_dir,  pkg + '-' + version + '*.whl'))[0]
+if os.path.basename(new_whl) != os.path.basename(wheel_path):
+    raise ValueError(f'Wheel tag changed, see {tmp_dir}')
+subprocess.check_call(['cp', new_whl, wheel_path])
+print(f'Added docs to {os.path.basename(wheel_path)} in-place')
+
+
+
+

doc_src/conf.py

@@ -11,44 +11,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os, datetime, sysconfig, platform
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-
-def build_lib_dir():
-    if sys.platform == 'darwin':
-        target = sysconfig.get_platform().split('-')[-1]
-        machine = platform.machine()
-        # Check if we're cross-compiling.  If so, module must already
-        # have been built for the host architecture.
-        if target == 'universal2':
-            python_platform = 'macosx-10.9-universal2'
-        elif target != machine:
-            python_platform = {'x86_64':'macosx-10.9-x86_64',
-                               'arm64': 'macosx-11-arm64'}[machine]
-        else:
-            python_platform = sysconfig.get_platform()
-
-    else:
-        python_platform = sysconfig.get_platform()
-
-    v0, v1 = sys.version_info[:2]
-    old_path = os.path.join(
-        '..',
-        'build',
-        f'lib.{python_platform}-{v0}.{v1}')
-    new_path = os.path.join(
-        '..',
-        'build',
-         f'lib.{python_platform}-cpython-{v0}{v1}')
-    return os.path.abspath(old_path), os.path.abspath(new_path)
-
-for path in build_lib_dir():
-    print('sys.path addition:', path)
-    sys.path.insert(0, path)
-
+import os
+import datetime
 import snappy
 print('Using: ' + snappy.__file__)
 
@@ -80,7 +44,6 @@ def build_lib_dir():
 
 # General information about the project.
 
-
 project = u'SnapPy'
 copyright = u'2009-%d, by Marc Culler, Nathan Dunfield, Matthias Goerner, Jeffrey Weeks and others' % datetime.datetime.now().year
 
@@ -177,9 +140,9 @@ def setup(app):
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
+
 html_theme_options = {
     'collapse_navigation': True,
-
     'navigation_depth': 5,
 }
 
@@ -247,37 +210,3 @@ def setup(app):
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'SnapPydoc'
-
-
-# -- Options for LaTeX output --------------------------------------------------
-
-# The paper size ('letter' or 'a4').
-#latex_paper_size = 'letter'
-
-# The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
-  ('index', 'SnapPy.tex', u'SnapPy Documentation',
-   u'Marc Culler ([email protected]) and Nathan Dunfield ([email protected])',
-   'manual'),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# Additional stuff for the LaTeX preamble.
-#latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_use_modindex = True

setup.py

@@ -182,7 +182,6 @@ class SnapPyBuildWheel(bdist_wheel):
         def run(self):
             python = sys.executable
             check_call([python, 'setup.py', 'build'])
-            check_call([python, 'setup.py', 'build_docs'])
             bdist_wheel.run(self)
         @staticmethod
         def check_command_available():