diff --git a/.github/workflows/book-gh-pages.yml b/.github/workflows/book-gh-pages.yml index 18564ae4..bef9695e 100644 --- a/.github/workflows/book-gh-pages.yml +++ b/.github/workflows/book-gh-pages.yml @@ -4,7 +4,9 @@ on: # Allows running this workflow manually workflow_dispatch: push: - branches: [master] + branches: + - master + - nixos-24.05 permissions: contents: read @@ -17,22 +19,38 @@ concurrency: jobs: deploy: if: "github.repository_owner == 'epics-extensions'" + permissions: pages: write id-token: write + environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + + # Checkout all documentation versions - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: + ref: main + path: dev persist-credentials: false + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + ref: nixos-24.05 + path: nixos-24.05 + persist-credentials: false + - uses: cachix/install-nix-action@3715ab1a11cac9e991980d7b4a28d80c7ebdd8f9 # v27 - - name: "Build documentation book" + - uses: DeterminateSystems/magic-nix-cache-action@87b14cf437d03d37989d87f0fa5ce4f5dc1a330b # v8 + + - name: "Build documentation books" run: | - nix build '.#docs' --print-build-logs - cp -Lr --no-preserve=mode,ownership ./result/share/doc/epnix/html ./book + nix run --print-build-logs './dev#ci-scripts/build-docs-multiversion' + - name: Setup Pages uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0 - name: Upload artifact diff --git a/docs/_static/multi-version.css b/docs/_static/multi-version.css new file mode 100644 index 00000000..3480bc58 --- /dev/null +++ b/docs/_static/multi-version.css @@ -0,0 +1,44 @@ +.multi-version { + font-size: var(--sidebar-item-font-size); + border-top: 1px solid var(--color-background-border); + margin-bottom: 1em; +} + +.multi-version summary { + color: var(--color-sidebar-caption-text); + font-size: var(--sidebar-caption-font-size); + font-weight: 700; + text-transform: uppercase; + + margin: 0; + padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal); +} + +.multi-version ul { + display: grid; + grid-template-columns: 1fr 1fr; + + list-style: none; + padding: 0; + margin: 0; +} + +.multi-version ul a { + box-sizing: border-box; + display: inline-block; + height: 100%; + line-height: var(--sidebar-item-line-height); + overflow-wrap: anywhere; + padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal); + text-decoration: none; + width: 100%; +} + +.multi-version summary:hover, +.multi-version ul a:hover { + background: var(--color-background-hover); +} + +.multi-version ul a.current { + font-weight: 700; +} diff --git a/docs/_templates/multi-version.html b/docs/_templates/multi-version.html new file mode 100644 index 00000000..11b0a47f --- /dev/null +++ b/docs/_templates/multi-version.html @@ -0,0 +1,18 @@ +{% if versions %} +
+
+ {{ _('Versions') }}: + +
+
+{% endif %} diff --git a/docs/conf.py b/docs/conf.py index e723fc36..1a94ae22 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,8 +3,10 @@ # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import json import os import sys +from pathlib import Path # Enables importing our custom "pygments_styles" module sys.path.append(os.path.abspath("./_ext")) @@ -15,6 +17,7 @@ project = "EPNix" copyright = "The EPNix Contributors" author = "The EPNix Contributors" +release = "dev" source_repository = "https://github.com/epics-extensions/EPNix" @@ -76,14 +79,16 @@ nix_options_json_files = ["./nixos-options.json"] + def nix_linkcode_resolve(path: str) -> str: return f"{source_repository}/blob/master/{path}" + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_static_path = ["_static"] -html_baseurl = "https://epics-extensions.github.io/EPNix/" +html_baseurl = f"https://epics-extensions.github.io/EPNix/{release}/" html_theme = "furo" html_theme_options = { @@ -115,6 +120,34 @@ def nix_linkcode_resolve(path: str) -> str: html_logo = "logo.svg" html_favicon = "favicon.svg" +# Multi version + +html_sidebars = { + "**": [ + "sidebar/brand.html", + "sidebar/search.html", + "sidebar/scroll-start.html", + "sidebar/navigation.html", + "sidebar/scroll-end.html", + "multi-version.html", + ] +} + +html_css_files = ["multi-version.css"] + +html_context = {} + +versions = Path("./versions.json") +if versions.exists(): + with versions.open() as f: + html_context["versions"] = json.load(f) + + # Mark current version as current + current_version = next( + el for el in html_context["versions"] if el["name"] == release + ) + current_version["current"] = True + # -- Options for Man output -------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-manual-page-output diff --git a/pkgs/ci-scripts/build-docs-multiversion.nix b/pkgs/ci-scripts/build-docs-multiversion.nix new file mode 100644 index 00000000..51013dda --- /dev/null +++ b/pkgs/ci-scripts/build-docs-multiversion.nix @@ -0,0 +1,47 @@ +{ + writeShellApplication, + writeText, + writers, + epnixLib, +}: let + stable = "nixos-24.05"; + versions = [ + "dev" + "nixos-24.05" + ]; + baseurl = "https://epics-extensions.github.io/EPNix"; + # Make a redirection using the tag, + # with a delay of 1 second, because Google considers them not permanent + # + # We need non-permanent redirections, because the redirection will change + # when a new stable version is released + redirect = writeText "stable-redirect.html" '' + + ''; + + versionInfo = ver: { + name = ver; + url = "${baseurl}/${ver}/"; + }; + versions_json = writers.writeJSON "versions.json" (map versionInfo versions); +in + writeShellApplication { + name = "build-docs-multiversion"; + + text = '' + for version in ${toString versions}; do + mkdir -p "./book/$version" + cp ${versions_json} "./$version/docs/versions.json" + git -C "$version" add docs/versions.json + nix build "./$version#docs" --print-build-logs + cp -LrT --no-preserve=mode,ownership ./result/share/doc/epnix/html "./book/$version" + done + cp ${redirect} ./book/index.html + ''; + + meta = { + description = "Build "; + maintainers = with epnixLib.maintainers; [minijackson]; + hidden = true; + }; + } diff --git a/pkgs/default.nix b/pkgs/default.nix index 295b3041..94ee79e8 100644 --- a/pkgs/default.nix +++ b/pkgs/default.nix @@ -106,5 +106,9 @@ in # Documentation support packages psu-simulator = callPackage ./doc-support/psu-simulator {}; + + ci-scripts = recurseExtensible (_self: { + build-docs-multiversion = callPackage ./ci-scripts/build-docs-multiversion.nix {}; + }); }); }