From 05a943c59d0b1e764c19af936f4f989b3743f125 Mon Sep 17 00:00:00 2001 From: Nathan Dunfield Date: Sat, 15 Jun 2024 15:49:09 -0500 Subject: [PATCH] Initial stab at moving the docs to a seperate build process --- .cirrus.yml | 28 ---------- .github/workflows/sage_test.yml | 5 ++ .github/workflows/wheels.yml | 16 +++--- doc_src/Makefile | 91 ++++----------------------------- doc_src/add_doc_to_wheel.py | 41 +++++++++++++++ doc_src/conf.py | 77 ++-------------------------- setup.py | 1 - 7 files changed, 68 insertions(+), 191 deletions(-) delete mode 100644 .cirrus.yml create mode 100755 doc_src/add_doc_to_wheel.py diff --git a/.cirrus.yml b/.cirrus.yml deleted file mode 100644 index 61d871c6c..000000000 --- a/.cirrus.yml +++ /dev/null @@ -1,28 +0,0 @@ -cirrus_wheels_macos_arm64_task: - name: Build wheels on macOS arm64. - macos_instance: - image: ghcr.io/cirruslabs/macos-ventura-xcode:latest - env: - CIBW_ARCHS_MACOS: arm64 - CIBW_SKIP: pp* cp38* cp312* - CIBW_BEFORE_BUILD: > - pip install cython FXrays 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_BEFORE_TEST: > - pip install cython 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_TEST_COMMAND: python -m snappy.test --skip-modern-opengl --skip-gui - install_pre_requirements_script: - - brew install python3 pipx - - python3 --version - run_cibuildwheel_script: - - pipx run cibuildwheel==2.17 --output-dir wheelhouse - wheels_artifacts: - path: "wheelhouse/*" - timeout_in: 40m diff --git a/.github/workflows/sage_test.yml b/.github/workflows/sage_test.yml index 8e392ac8b..2b98dfabb 100644 --- a/.github/workflows/sage_test.yml +++ b/.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 diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 7b5777457..96c63856b 100644 --- a/.github/workflows/wheels.yml +++ b/.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 diff --git a/doc_src/Makefile b/doc_src/Makefile index 3555401b4..652e5be30 100644 --- a/doc_src/Makefile +++ b/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 ' where 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." diff --git a/doc_src/add_doc_to_wheel.py b/doc_src/add_doc_to_wheel.py new file mode 100755 index 000000000..9503d1223 --- /dev/null +++ b/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') + + + + diff --git a/doc_src/conf.py b/doc_src/conf.py index 074215e87..6602f86da 100644 --- a/doc_src/conf.py +++ b/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 (culler@math.uic.edu) and Nathan Dunfield (nmd@illinois.edu)', - '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 diff --git a/setup.py b/setup.py index 337a3ccd9..03b2abfc6 100644 --- a/setup.py +++ b/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():