Add the go-scikit documentation site

.github/workflows/docs.yml

@@ -0,0 +1,230 @@
+name: docs
+
+# Every documentation version is a separate Hugo build, published under
+# https://go-scikit.github.io/docs/<version>/ on the gh-pages branch, where
+# <version> is the newest minor version among the libraries the pages describe
+# (params.libraries in hugo.yaml: v0.1.2 -> 0.1), or "main" while none of
+# them is tagged. main is that version's source: each push to main replaces /docs/<version>/, and
+# /docs/latest/ follows the newest. Pull requests build and check, and publish
+# nothing.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+# The build needs nothing beyond the source. Write access to the repository
+# is granted to the deploy job alone, below, so a pull request build cannot
+# push to gh-pages.
+permissions:
+  contents: read
+
+env:
+  HUGO_VERSION: "0.167.0"
+  # sha256 of hugo_${HUGO_VERSION}_linux-amd64.tar.gz, from the release's checksums.txt.
+  HUGO_SHA256: "4d84519b9f619e6d4c3fb45a50157abeabeb724f859c60605f44c23def6e1169"
+  DOCS_URL: "https://go-scikit.github.io/docs"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          # themes/hextra (the tannevaled/hextra fork, pinned to a release tag)
+          # and branding (go-scikit/brand) are submodules.
+          submodules: recursive
+          # The whole history: each page's creation and modification come from git.
+          fetch-depth: 0
+
+      - name: Install Hugo ${{ env.HUGO_VERSION }}
+        run: |
+          curl -fsSL -o /tmp/hugo.tar.gz \
+            "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/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+          echo "${HUGO_SHA256}  /tmp/hugo.tar.gz" | sha256sum -c -
+          sudo tar -xzf /tmp/hugo.tar.gz -C /usr/local/bin hugo
+          hugo version
+
+      # The version label is the newest minor version among the libraries
+      # params.libraries in hugo.yaml names ("main" until one is released), and
+      # it is the last segment of baseURL: the version selector reads it there.
+      - name: Version
+        id: version
+        run: |
+          set -euo pipefail
+          libs=$(hugo config --format json | jq -r '.params.libraries | to_entries[] | "\(.key) \(.value)"')
+          test -n "${libs}" || { echo "::error::params.libraries in hugo.yaml is empty"; exit 1; }
+          minors=""
+          while read -r name tag; do
+            if [ "${tag}" = main ]; then continue; fi
+            minor=$(printf '%s\n' "${tag}" | sed -nE 's/^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/\1.\2/p')
+            if [ -z "${minor}" ]; then
+              echo "::error::params.libraries.${name} in hugo.yaml is \"${tag}\", not vMAJOR.MINOR.PATCH or main"
+              exit 1
+            fi
+            minors=$(printf '%s\n%s\n' "${minors}" "${minor}")
+          done <<< "${libs}"
+          version=$(printf '%s\n' "${minors}" | sed '/^$/d' | sort -t. -k1,1nr -k2,2nr | sed -n 1p)
+          version=${version:-main}
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+          echo "libraries: $(echo ${libs}); documentation version ${version}"
+
+      # Each page's creation (first commit, followed across renames) and its
+      # author, for the page history at its foot (params.page.history).
+      - name: Page history
+        run: |
+          mkdir -p data
+          sh themes/hextra/scripts/page-history.sh > data/pagehistory.json
+
+      # --panicOnWarning: a deprecated setting or a template warning fails the
+      # build rather than scrolling by. A broken {{< relref >}} is an error.
+      - name: Build
+        env:
+          HUGO_ENVIRONMENT: production
+        run: >-
+          hugo --gc --minify --panicOnWarning --printPathWarnings
+          --baseURL "${DOCS_URL}/${{ steps.version.outputs.version }}/"
+
+      # Internal links and anchors, offline, with the site laid out under
+      # /docs/<version>/ as it is served.
+      - name: Lay out the site for the link check
+        run: |
+          mkdir -p _check/docs
+          cp -R public "_check/docs/${{ steps.version.outputs.version }}"
+
+      - name: Check links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --offline --no-progress --include-fragments
+            --index-files index.html
+            --root-dir ${{ github.workspace }}/_check
+            '_check/docs/**/*.html'
+          fail: true
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: site
+          path: public
+          retention-days: 7
+
+  # The offline check above proves the site's own links and anchors. An
+  # https:// URL is text to it: this job fetches each one the pages name.
+  links:
+    name: every external link resolves
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Check
+        run: |
+          set -uo pipefail
+          # The character class matters: an extractor stopping only at ) and "
+          # carries a closing > or < into the request.
+          urls=$(grep -rhoE 'https?://[^)">< [:space:]]+' content/ README.md | sed -E 's/[.,`]+$//' | sort -u)
+          test -n "$urls" || { echo "::error::no links found; are the pages still there?"; exit 1; }
+          echo "checking $(printf '%s\n' "$urls" | wc -l) distinct URLs"
+          fail=0
+          while read -r u; do
+            case "$u" in
+              # Renders whatever it is asked for; proves nothing.
+              *img.shields.io*) continue ;;
+              # Documented placeholders, not hosts.
+              *example.com*|*example.org*|*example.net*|*localhost*|*127.0.0.1*|*.invalid*) continue ;;
+              # This site's own pages: they exist only once this workflow
+              # has deployed them, and the offline check above already
+              # proves every link inside the site.
+              *go-scikit.github.io/docs*) continue ;;
+              # This repository's own files: on a pull request that adds
+              # them, they are not on main yet.
+              *github.com/go-scikit/docs/*) continue ;;
+            esac
+            # github.com answers curl's blob pages with 503 most of the time,
+            # while the raw host answers 200 for a file and 404 for a missing
+            # one. A blob link claims "this file exists at this ref", so ask
+            # the raw host (as the landing's links.yml and go-ndarray/docs#30).
+            probe=$u
+            case "$u" in
+              https://github.com/*/*/blob/*)
+                probe=https://raw.githubusercontent.com/$(printf '%s' "${u#https://github.com/}" | sed -E 's#^([^/]+/[^/]+)/blob/#\1/#; s/[?#].*$//') ;;
+            esac
+            # Three attempts: one is a flake detector rather than a link
+            # checker, and a lane that fails at random gets ignored.
+            code=000
+            for _ in 1 2 3; do
+              code=$(curl -sS -o /dev/null -w '%{http_code}' -L --max-time 25 "$probe" 2>/dev/null) || true
+              code=${code:-000}
+              case "$code" in 2*|3*) break ;; esac
+              sleep 3
+            done
+            case "$code" in
+              2*|3*) printf '  ok   %s  %s\n' "$code" "$u" ;;
+              *)     printf '  FAIL %s  %s\n' "$code" "$u"; fail=1 ;;
+            esac
+          done <<< "$urls"
+          test "$fail" -eq 0 || { echo "::error::at least one link does not resolve"; exit 1; }
+
+  deploy:
+    # Only main publishes. A pull request stops after build above: it has no
+    # business pushing to gh-pages.
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    # Never two deploys at once: both would push gh-pages and the second would
+    # be rejected. cancel-in-progress stays false -- killing a publish half way
+    # through is worse than making it wait.
+    concurrency:
+      group: gh-pages-deploy
+      cancel-in-progress: false
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      # The publishing script, from the commit being published.
+      - uses: actions/checkout@v7
+        with:
+          path: source
+
+      # The published site. Only the version being built is replaced; every
+      # other version stays as it is. The first deploy finds no gh-pages
+      # branch and starts it empty (orphan): nothing else ever creates it.
+      - uses: actions/checkout@v7
+        with:
+          path: gh-pages
+          fetch-depth: 0
+
+      - name: Switch to gh-pages
+        working-directory: gh-pages
+        run: |
+          if git ls-remote --exit-code --heads origin gh-pages >/dev/null; then
+            git fetch -q origin gh-pages
+            git checkout -q -B gh-pages FETCH_HEAD
+          else
+            echo "no gh-pages branch yet: starting one"
+            git checkout -q --orphan gh-pages
+            git rm -rqf .
+            git clean -fdxq
+          fi
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: site
+          path: site
+
+      - name: Publish ${{ needs.build.outputs.version }}
+        run: source/scripts/publish-version.sh "${{ needs.build.outputs.version }}" site gh-pages
+
+      - name: Push gh-pages
+        working-directory: gh-pages
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          if git diff --cached --quiet; then
+            echo "nothing changed"
+            exit 0
+          fi
+          git commit -q -m "Deployed ${GITHUB_SHA::7} to ${{ needs.build.outputs.version }} with Hugo ${HUGO_VERSION}"
+          git push origin HEAD:gh-pages

.gitignore

@@ -0,0 +1,8 @@
+/public/
+/resources/
+/_check/
+.hugo_build.lock
+.DS_Store
+
+# Written by themes/hextra/scripts/page-history.sh before each build (CI and local).
+/data/pagehistory.json

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "themes/hextra"]
+	path = themes/hextra
+	url = https://github.com/tannevaled/hextra.git
+[submodule "branding"]
+	path = branding
+	url = https://github.com/go-scikit/brand.git

README.md

@@ -1,2 +1,24 @@
-# docs
-Documentation site for the go-scikit scientific stack for Go
+# go-scikit/docs
+
+The documentation site of the [go-scikit](https://github.com/go-scikit)
+umbrella, served at <https://go-scikit.github.io/docs/>.
+
+Hugo with the [tannevaled/hextra](https://github.com/tannevaled/hextra) fork
+(submodule `themes/hextra`, pinned at v0.16.0) and the
+[go-scikit/brand](https://github.com/go-scikit/brand) marks (submodule
+`branding`). Each documentation version is a separate build published to the
+`gh-pages` branch by `.github/workflows/docs.yml`; the version label is the
+newest minor among `params.libraries` in `hugo.yaml`.
+
+- Landing: <https://go-scikit.github.io/>
+- Roadmap and status: <https://github.com/go-scikit/roadmap>
+
+## Build
+
+```sh
+git submodule update --init
+sh themes/hextra/scripts/page-history.sh > data/pagehistory.json
+hugo server
+```
+
+BSD-3-Clause.

assets/css/custom.css

@@ -0,0 +1,35 @@
+/* go-scikit branding on Hextra (github.com/go-scikit/brand).
+ *
+ * The mark's gradient, #8FA3C8 -> #2F3E63 (branding/svg/color/go-scikit.svg).
+ * Hextra derives its whole primary scale (links, active sidebar entry,
+ * buttons) from these three variables.
+ *
+ * Light theme: #2F3E63 = hsl(223 36% 29%), the gradient's dark end
+ *              (10.55:1 on white).
+ * Dark theme:  #8FA3C8 = hsl(219 34% 67%), its light end. */
+:root {
+  --primary-hue: 223deg;
+  --primary-saturation: 36%;
+  --primary-lightness: 29%;
+}
+.dark {
+  --primary-hue: 219deg;
+  --primary-saturation: 34%;
+  --primary-lightness: 67%;
+}
+
+/* Tables: their headers stand out in the brand colour and their text is a
+ * size smaller than the prose. In the dark theme the header keeps the dark
+ * end: white on #8FA3C8 cannot be read. */
+.content table { font-size: 0.875em; }
+.content table th { background: #2F3E63; color: #fff; }
+
+/* The version selector's list hangs from its button's right edge, so that it
+ * stays on screen at the end of the navbar. */
+.fs-version-select .hextra-nav-menu-items { left: auto !important; right: 0; transform: none !important; }
+
+/* The outdated-version banner (layouts/_partials/custom/content-begin.html). */
+.nd-outdated { margin-top: 1rem; padding: 0.75rem 1rem; border-radius: 0.5rem;
+  border: 1px solid #f59e0b; background: #fffbeb; color: #78350f; }
+.dark .nd-outdated { background: #451a03; color: #fde68a; border-color: #b45309; }
+.nd-outdated a { text-decoration: underline; font-weight: 600; }

content/en/_index.md

@@ -0,0 +1,53 @@
+---
+title: "go-scikit documentation"
+linkTitle: "Home"
+type: docs
+cascade:
+  type: docs
+description: "The scientific stack for Go, in pure Go (CGO=0), and the organisations that extend it towards MATLAB and Mathematica."
+---
+
+**go-scikit is the umbrella over the organisations that make up a scientific
+stack for Go.** Each one is a library, or a few, with its own site,
+documentation and release cycle. There is no cgo and no C library: one
+`go build` gives a static binary. Where a library is slower or less accurate
+than its Python reference, its own documentation says so.
+
+## The established organisations
+
+| Organisation | What it is | Landing | Documentation |
+| --- | --- | --- | --- |
+| [go-ndarray](https://github.com/go-ndarray) | N-dimensional arrays, `numpy.linalg`, `numpy.fft`, `numpy.random` | [site](https://go-ndarray.github.io/) | [docs](https://go-ndarray.github.io/docs/) |
+| [go-fft](https://github.com/go-fft) | `numpy.fft` and `scipy.fft` equivalents | [site](https://go-fft.github.io/) | [docs](https://go-fft.github.io/docs/) |
+| [go-numerics](https://github.com/go-numerics) | optimisation, quadrature and ODE solvers, special functions | [site](https://go-numerics.github.io/) | [docs](https://go-numerics.github.io/docs/) |
+| [go-statistics](https://github.com/go-statistics) | distributions, descriptive statistics, statistical tests | [site](https://go-statistics.github.io/) | [docs](https://go-statistics.github.io/docs/) |
+| [go-dataframe](https://github.com/go-dataframe) | labelled tables | [site](https://go-dataframe.github.io/) | [docs](https://go-dataframe.github.io/docs/) |
+| [go-plot](https://github.com/go-plot) | matplotlib-class figures | [site](https://go-plot.github.io/) | [docs](https://go-plot.github.io/docs/) |
+| [go-notebook](https://github.com/go-notebook) | compiled, reactive Go notebooks | [site](https://go-notebook.github.io/) | [docs](https://go-notebook.github.io/docs/) |
+
+## The parity-plan organisations
+
+The [roadmap](https://github.com/go-scikit/roadmap) plans feature parity with
+MATLAB and Mathematica. Wave 1 is under way, in four organisations:
+
+| Organisation | Package | Status | Pages |
+| --- | --- | --- | --- |
+| go-approx | [interp](https://github.com/go-approx/interp) | released v0.1.0 | [go-approx]({{< relref "approx" >}}) |
+| go-approx | [poly](https://github.com/go-approx/poly) | released v0.1.0 | [go-approx]({{< relref "approx" >}}) |
+| go-dsp | [signal](https://github.com/go-dsp/signal) | released v0.1.0 | [go-dsp]({{< relref "dsp" >}}) |
+| go-sparse | [sparse](https://github.com/go-sparse/sparse) | released v0.1.0 | [go-sparse]({{< relref "sparse" >}}) |
+| go-bignum | [bigfloat](https://github.com/go-bignum/bigfloat) | in development, not yet tagged | [go-bignum]({{< relref "bignum" >}}) |
+
+The other organisations of the plan (go-symbolic, go-mlkit, go-autodiff,
+go-geometry, go-fem, go-graphalgo, go-control, go-units, go-sciio) are
+planned; nothing is released there.
+
+"Released" means a tag exists. The status of every item, with its evidence, is
+in [STATUS.md](https://github.com/go-scikit/roadmap/blob/main/STATUS.md).
+
+## Where else
+
+- The portal: [go-scikit.github.io](https://go-scikit.github.io/).
+- The plan: [go-scikit/roadmap](https://github.com/go-scikit/roadmap) (PLAN.md,
+  STATUS.md, bibliography).
+- The marks: [go-scikit/brand](https://github.com/go-scikit/brand).

content/en/approx.md

@@ -0,0 +1,27 @@
+---
+title: "go-approx"
+description: "Interpolation, splines and polynomials. interp and poly are released v0.1.0."
+---
+
+go-approx is the home of approximation in the parity plan: interpolation,
+splines, polynomials, and later Chebyshev and AAA approximation and scattered
+data.
+
+| Package | Status | Repository |
+| --- | --- | --- |
+| interp | released v0.1.0 | [go-approx/interp](https://github.com/go-approx/interp) |
+| poly | released v0.1.0 | [go-approx/poly](https://github.com/go-approx/poly) |
+
+## What is verified
+
+From [STATUS.md](https://github.com/go-scikit/roadmap/blob/main/STATUS.md):
+`numpy.interp`, `interp1d`, PCHIP, Akima and `poly1d` are bit-identical to
+NumPy and SciPy; splines agree within 1e-15 to 1e-10. The remaining `interp`
+gaps are in progress. The speed comparison with the Python reference is in
+[interp's docs/perf.md](https://github.com/go-approx/interp/blob/main/docs/perf.md).
+
+## Where to read more
+
+- Landing: [go-approx.github.io](https://go-approx.github.io/)
+- Documentation: [go-approx.github.io/docs](https://go-approx.github.io/docs/)
+- Organisation: [github.com/go-approx](https://github.com/go-approx)