From 902fc14069caad0af6af7b55cbf649134703f9b5 Mon Sep 17 00:00:00 2001 From: Seyon Sivarajah Date: Wed, 3 Jul 2024 09:49:56 +0100 Subject: [PATCH] docs(hugr-py): build and publish docs (#1253) Closes #1215 Will build and publish for main branch + every tagged version with docs (currently none), using [sphinx-multiversion](https://holzhaus.github.io/sphinx-multiversion/master/index.html) With multiple versions looks like: ![image](https://github.com/CQCL/hugr/assets/12997250/f54738cf-d38f-4be7-a370-e34ab986482b) Will follow-up with a PR adding links to readme etc. once I've seen the workflow succeeds. --- .github/workflows/docs.yml | 63 +++++++++++++++++++ hugr-py/docs/_static/_redirect.html | 9 +++ .../docs/api-docs/_templates/versioning.html | 8 +++ hugr-py/docs/api-docs/conf.py | 13 ++++ hugr-py/docs/build.sh | 5 +- hugr-py/poetry.lock | 16 ++++- hugr-py/pyproject.toml | 1 + 7 files changed, 112 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 hugr-py/docs/_static/_redirect.html create mode 100644 hugr-py/docs/api-docs/_templates/versioning.html diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..2f22b7579 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,63 @@ +name: Build and publish docs + +on: + workflow_dispatch: + push: + branches: + - main + # only run if there are changes in the hugr-py directory + paths: + - 'hugr-py/**' + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run +# in-progress and latest queued. +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build: + name: Build docs. + runs-on: ubuntu-latest + defaults: + run: + working-directory: ./hugr-py + steps: + - uses: actions/checkout@v4 + - name: Install poetry + run: pipx install poetry + - name: Set up Python '3.10' + uses: actions/setup-python@v5 + with: + python-version: '3.10' + cache: "poetry" + - name: Install HUGR + run: poetry install --with docs + - name: Build docs + run: | + cd docs + ./build.sh + - name: Upload artifact. + uses: actions/upload-pages-artifact@v3 + with: + path: ./hugr-py/docs/build + + publish: + name: Publish docs. + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Deploy to GitHub Pages. + id: deployment + uses: actions/deploy-pages@v4 diff --git a/hugr-py/docs/_static/_redirect.html b/hugr-py/docs/_static/_redirect.html new file mode 100644 index 000000000..3f20c9c91 --- /dev/null +++ b/hugr-py/docs/_static/_redirect.html @@ -0,0 +1,9 @@ + + + + Redirecting to main branch + + + + + diff --git a/hugr-py/docs/api-docs/_templates/versioning.html b/hugr-py/docs/api-docs/_templates/versioning.html new file mode 100644 index 000000000..7c5ab1474 --- /dev/null +++ b/hugr-py/docs/api-docs/_templates/versioning.html @@ -0,0 +1,8 @@ +{% if versions %} +

{{ _('Versions') }}

+ +{% endif %} diff --git a/hugr-py/docs/api-docs/conf.py b/hugr-py/docs/api-docs/conf.py index 98ecdd0db..ceace6b8d 100644 --- a/hugr-py/docs/api-docs/conf.py +++ b/hugr-py/docs/api-docs/conf.py @@ -13,6 +13,7 @@ "sphinx.ext.autosummary", "sphinx.ext.viewcode", "sphinx.ext.intersphinx", + "sphinx_multiversion", ] html_theme = "sphinx_book_theme" @@ -36,6 +37,18 @@ templates_path = ["_templates"] exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "conftest.py"] +html_sidebars = { + "**": [ + "navbar-logo.html", + "icon-links.html", + "search-button-field.html", + "sbt-sidebar-nav.html", + "versioning.html", + ], +} + +smv_branch_whitelist = "main" +smv_tag_whitelist = r"^hugr-py-.*$" intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), diff --git a/hugr-py/docs/build.sh b/hugr-py/docs/build.sh index 57eef23b6..d4e51e3bb 100755 --- a/hugr-py/docs/build.sh +++ b/hugr-py/docs/build.sh @@ -3,5 +3,6 @@ mkdir build touch build/.nojekyll # Disable jekyll to keep files starting with underscores - -sphinx-build -b html ./api-docs ./build/api-docs +# copy redirect file +cp ./_static/_redirect.html ./build/index.html +sphinx-multiversion ./api-docs ./build diff --git a/hugr-py/poetry.lock b/hugr-py/poetry.lock index 2006a16d2..555981053 100644 --- a/hugr-py/poetry.lock +++ b/hugr-py/poetry.lock @@ -576,6 +576,20 @@ code-style = ["pre-commit"] doc = ["ablog", "folium", "ipywidgets", "matplotlib", "myst-nb", "nbclient", "numpy", "numpydoc", "pandas", "plotly", "sphinx-copybutton", "sphinx-design", "sphinx-examples", "sphinx-tabs", "sphinx-thebe", "sphinx-togglebutton", "sphinxcontrib-bibtex", "sphinxcontrib-youtube", "sphinxext-opengraph"] test = ["beautifulsoup4", "coverage", "defusedxml", "myst-nb", "pytest", "pytest-cov", "pytest-regressions", "sphinx_thebe"] +[[package]] +name = "sphinx-multiversion" +version = "0.2.4" +description = "Add support for multiple versions to sphinx" +optional = false +python-versions = "*" +files = [ + {file = "sphinx-multiversion-0.2.4.tar.gz", hash = "sha256:5cd1ca9ecb5eed63cb8d6ce5e9c438ca13af4fa98e7eb6f376be541dd4990bcb"}, + {file = "sphinx_multiversion-0.2.4-py3-none-any.whl", hash = "sha256:dec29f2a5890ad68157a790112edc0eb63140e70f9df0a363743c6258fbeb478"}, +] + +[package.dependencies] +sphinx = ">=2.1" + [[package]] name = "sphinxcontrib-applehelp" version = "1.0.8" @@ -712,4 +726,4 @@ zstd = ["zstandard (>=0.18.0)"] [metadata] lock-version = "2.0" python-versions = ">=3.10" -content-hash = "0e927e63660da3f23f2e241a006c7255a780303326e967baec4f0436f16bbd84" +content-hash = "c0e0f4ebdc6d0b9e2b6e71841109ee1a47f42d850aa5621c5723006a9dd9d99a" diff --git a/hugr-py/pyproject.toml b/hugr-py/pyproject.toml index 739ced174..a86abf544 100644 --- a/hugr-py/pyproject.toml +++ b/hugr-py/pyproject.toml @@ -33,6 +33,7 @@ optional = true [tool.poetry.group.docs.dependencies] sphinx = "^7.2.6" sphinx-book-theme = "^1.1.2" +sphinx-multiversion = "^0.2.4" [build-system] requires = ["poetry-core"]