diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 04f26c4..e2f4418 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -1,43 +1,47 @@ name: Deploy documentation to GH pages on: - push: - branches: - - main - paths: - - 'docs/**' - - '.github/workflows/documentation.yml' release: types: [published] workflow_dispatch: + inputs: + tag: + description: Release tag to build the documentation from + required: true permissions: - contents: write + contents: read + pages: write + id-token: write concurrency: - group: gh-pages + group: pages cancel-in-progress: false jobs: deploy: + if: ${{ !github.event.release.prerelease }} + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest steps: + - uses: actions/configure-pages@v6 - uses: actions/checkout@v7 with: - fetch-depth: 0 + ref: refs/tags/${{ github.event.release.tag_name || inputs.tag }} - uses: actions/setup-python@v7 with: python-version: 3.x - - run: pip install zensical "mike @ git+https://github.com/squidfunk/mike.git" - - name: Configure git identity + - run: pip install zensical + - name: Reject tags with versioned documentation run: | - git config user.name "github-actions[bot]" - git config user.email "github-actions[bot]@users.noreply.github.com" - - name: Deploy dev version from main - if: github.ref == 'refs/heads/main' - run: cd docs && mike deploy --push --update-aliases dev - - name: Deploy released version from release tag - if: github.event_name == 'release' && !github.event.release.prerelease - run: | - cd docs - mike deploy --push --update-aliases "${{ github.event.release.tag_name }}" latest - mike set-default --push latest + if grep -qFx '[project.extra.version]' docs/zensical.toml; then + echo "::error::this tag still builds versioned documentation with mike, deploy from a later release" + exit 1 + fi + - run: cd docs && zensical build --clean --strict + - uses: actions/upload-pages-artifact@v5 + with: + path: docs/site + - uses: actions/deploy-pages@v5 + id: deployment diff --git a/README.md b/README.md index 0530756..177eebc 100644 --- a/README.md +++ b/README.md @@ -45,15 +45,15 @@ A typical sequence of stages would be: - application of PUE / WUE and other overheads - application of carbon intensity factors -Have a look at the [methodology section](https://opensourcegreenops.cloud/latest/methodology/) of our documentation for more details. +Have a look at the [methodology section](https://opensourcegreenops.cloud/methodology/) of our documentation for more details. ## Documentation -The documentation is at https://opensourcegreenops.cloud/. If you can't wait to try SPRUCE, have a look at the [tutorial for Docker](https://opensourcegreenops.cloud/latest/tutorial/with-docker/). +The documentation is at https://opensourcegreenops.cloud/. If you can't wait to try SPRUCE, have a look at the [tutorial for Docker](https://opensourcegreenops.cloud/tutorial/with-docker/). To explore enriched output, see -[Explore the results](https://opensourcegreenops.cloud/latest/tutorial/results/) -and [Build a simple dashboard](https://opensourcegreenops.cloud/latest/howto/dashboard/). +[Explore the results](https://opensourcegreenops.cloud/tutorial/results/) +and [Build a simple dashboard](https://opensourcegreenops.cloud/howto/dashboard/). ## License Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0 diff --git a/docs/README.md b/docs/README.md index f045513..46364cf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,18 +1,4 @@ source .venv/bin/activate zensical serve -## Versioned docs - -Versioning uses [mike](https://github.com/squidfunk/mike) (Zensical fork). Install it with: - - pip install "mike @ git+https://github.com/squidfunk/mike.git" - -Preview the versioned site (with the version selector) locally: - - mike serve - -Releases are published automatically by `.github/workflows/documentation.yml`: pushes to `main` update the `dev` alias, and publishing a GitHub release publishes a numbered version (the release tag) aliased to `latest`. - -https://zensical.org/docs/setup/versioning/ - - +The site is built from a release tag by `.github/workflows/documentation.yml`, either when a GitHub release is published or by hand for a given tag, so it describes a release rather than `main`. diff --git a/docs/overrides/main.html b/docs/overrides/main.html index d4b89f2..68ae4af 100644 --- a/docs/overrides/main.html +++ b/docs/overrides/main.html @@ -21,9 +21,7 @@ {% set page_desc = page.meta.description if page.meta and page.meta.description else config.site_description %} {% set page_url = page.canonical_url if page.canonical_url else config.site_url %} - {#- mike rewrites site_url to carry the version segment and drops the trailing slash - (https://opensourcegreenops.cloud/dev), while the configured value keeps it. Join the - path onto either shape, then collapse the doubled slash the trailing form produces. -#} + {#- Tolerate site_url with or without a trailing slash. -#} {% set card_url = (config.site_url ~ "/images/social-card.png") | replace("//images/", "/images/") %} diff --git a/docs/src/robots.txt b/docs/src/robots.txt new file mode 100644 index 0000000..6a1d2a3 --- /dev/null +++ b/docs/src/robots.txt @@ -0,0 +1,4 @@ +User-agent: * +Allow: / + +Sitemap: https://opensourcegreenops.cloud/sitemap.xml diff --git a/docs/zensical.toml b/docs/zensical.toml index 95ad42c..3511172 100644 --- a/docs/zensical.toml +++ b/docs/zensical.toml @@ -93,11 +93,6 @@ nav = [ docs_dir = "src" -[project.extra.version] -provider = "mike" -default = "latest" -alias = true - # ---------------------------------------------------------------------------- # Section for configuring theme options # ----------------------------------------------------------------------------