diff --git a/.github/workflows/python-app.yml b/.github/workflows/python-app.yml index 092a8aa8..19920c85 100644 --- a/.github/workflows/python-app.yml +++ b/.github/workflows/python-app.yml @@ -41,12 +41,12 @@ jobs: python -m pytest - name: Sphinx documentation build run: | - make docs + bash docs/build-docs.sh - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v4 if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' && matrix.deploy-gh-pages }} with: publish_branch: gh-pages github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: docs/build/html/ + publish_dir: docs/build/ force_orphan: true diff --git a/.gitignore b/.gitignore index 5774c658..f80b1717 100644 --- a/.gitignore +++ b/.gitignore @@ -70,6 +70,9 @@ instance/ # Sphinx documentation docs/_build/ +docs/pyproject.toml +docs/poetry.lock +docs/build # PyBuilder .pybuilder/ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000..fdc8b037 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,4 @@ +[submodule "docs/pytket-docs-theming"] + path = docs/pytket-docs-theming + url = https://github.com/CQCL/pytket-docs-theming.git + branch = main diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf1..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..6e20b650 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,5 @@ +# Building the docs + +The docs are built by using the [pytket-docs-theming](https://github.com/CQCL/pytket-docs-theming/) repository as a git submodule. If there are issues with the docs build, feel free to open an issue or pull request there. + +For instructions on how to build the docs, take a look at the [extensions README](https://github.com/CQCL/pytket-docs-theming/blob/main/extensions/README.md). diff --git a/docs/build-docs.sh b/docs/build-docs.sh new file mode 100644 index 00000000..d96cdc22 --- /dev/null +++ b/docs/build-docs.sh @@ -0,0 +1,20 @@ +rm -rf build/ + +# Move theming elements into the docs folder +cp -R pytket-docs-theming/_static . +cp -R pytket-docs-theming/quantinuum-sphinx . +cp pytket-docs-theming/conf.py . + +# Get the name of the project +EXTENSION_NAME="$(basename "$(dirname `pwd`)")" + +# Correct github link in navbar +sed -i '' 's#CQCL/tket#CQCL/'$EXTENSION_NAME'#' _static/nav-config.js + +# Build the docs. Ensure we have the correct project title. +sphinx-build -b html -D html_title="$EXTENSION_NAME" . build + +# Remove copied files. This ensures reusability. +rm -r _static +rm -r quantinuum-sphinx +rm conf.py diff --git a/docs/source/index.rst b/docs/index.rst similarity index 100% rename from docs/source/index.rst rename to docs/index.rst diff --git a/docs/install.sh b/docs/install.sh new file mode 100644 index 00000000..379bca1b --- /dev/null +++ b/docs/install.sh @@ -0,0 +1,9 @@ + +# Copy over poetry dependencies from theming repository +cp pytket-docs-theming/extensions/pyproject.toml . +cp pytket-docs-theming/extensions/poetry.lock . + +# Install the docs dependencies. Creates a .venv directory in docs +poetry install + +# NOTE: Editable wheel should be installed separately. diff --git a/docs/source/modules.rst b/docs/modules.rst similarity index 100% rename from docs/source/modules.rst rename to docs/modules.rst diff --git a/docs/pytket-docs-theming b/docs/pytket-docs-theming new file mode 160000 index 00000000..7141e767 --- /dev/null +++ b/docs/pytket-docs-theming @@ -0,0 +1 @@ +Subproject commit 7141e767a94c13d818e94669b3aaafba76e9348a diff --git a/docs/source/pytket.phir.rebasing.rst b/docs/pytket.phir.rebasing.rst similarity index 100% rename from docs/source/pytket.phir.rebasing.rst rename to docs/pytket.phir.rebasing.rst diff --git a/docs/source/pytket.phir.rst b/docs/pytket.phir.rst similarity index 100% rename from docs/source/pytket.phir.rst rename to docs/pytket.phir.rst diff --git a/docs/source/pytket.phir.sharding.rst b/docs/pytket.phir.sharding.rst similarity index 100% rename from docs/source/pytket.phir.sharding.rst rename to docs/pytket.phir.sharding.rst diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index e8139fed..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,46 +0,0 @@ -############################################################################## -# -# Copyright (c) 2023 Quantinuum LLC All rights reserved. -# Use of this source code is governed by a BSD-style -# license that can be found in the LICENSE file. -# -############################################################################## - -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. -import datetime -import pathlib -import sys -from importlib.metadata import version as get_version - -sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix()) - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -project = "pytket-phir" -project_copyright = f"2023-{datetime.date.today().year}, Quantinuum LLC" -author = "Quantinuum LLC" -release: str = ".".join(get_version("pytket-phir").split(".")[:2]) - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = [ - "sphinx.ext.doctest", - "sphinx.ext.autodoc", - "sphinx.ext.napoleon", -] - -exclude_patterns = [] - - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -html_theme = "pydata_sphinx_theme"