ptycho · daurer · Nov 28, 2024 · Nov 28, 2024 · Dec 9, 2024 · Dec 18, 2024
diff --git a/.github/pages/index.html b/.github/pages/index.html
@@ -0,0 +1,5 @@
+<html>
+ <head>
+  <meta http-equiv="refresh" content="0; url=legacy/" />
+ </head>
+</html>
diff --git a/.github/pages/switcher.py b/.github/pages/switcher.py
@@ -0,0 +1,41 @@
+"""Create/modify switcher.json to allow docs to switch between different versions."""
+
+import json, os
+from argparse import ArgumentParser
+from pathlib import Path
+
+
+def get_versions(root: str) -> list[str]:
+    """Generate a list of versions."""
+    versions = sorted([ f.name for f in os.scandir(root) if f.is_dir() ])
+    print(f"Sorted versions: {versions}")
+    return versions
+
+
+def write_json(path: Path, repository: str, versions: list[str]):
+    """Write the JSON switcher to path."""
+    org, repo_name = repository.split("/")
+    struct = [
+        {"version": version, "url": f"https://{org}.github.io/{repo_name}/{version}/"}
+        for version in versions
+    ]
+    text = json.dumps(struct, indent=2)
+    print(f"JSON switcher:\n{text}")
+    path.write_text(text, encoding="utf-8")
+
+
+def main(args=None):
+    """Parse args and write switcher."""
+    parser = ArgumentParser(description="Make a versions.json file")
+    parser.add_argument("root", type=Path, help="Path to root directory with all versions of docs")
+    parser.add_argument("repository", help="The GitHub org and repository name: ORG/REPO")
+    parser.add_argument("output", type=Path, help="Path of write switcher.json to")
+    args = parser.parse_args(args)
+
+    # Write the versions file
+    versions = get_versions(args.root)
+    write_json(args.output, args.repository, versions)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.github/workflows/_build_docs.yaml b/.github/workflows/_build_docs.yaml
@@ -0,0 +1,52 @@
+on:
+  workflow_call:
+    inputs:
+      tag:
+        type: string
+        description: A tag for the docs artifact
+        required: true
+
+jobs:
+  build_new_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PtyPy Code
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+          check-latest: true
+
+      - name: Setup MPI
+        uses: mpi4py/setup-mpi@v1
+        with:
+          mpi: mpich
+
+      - name: Install Sphinx
+        run: pip install sphinx myst_parser
+
+      - name: Install PtyPy
+        run: pip install .[full]
+
+      - name: Install docs dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Set Path to Sphinx Build
+        run: echo "SPHINXBUILD=`which sphinx-build`" >> $GITHUB_ENV
+
+      - name: Build Sphinx Documentation
+        working-directory: docs
+        run: make html
+
+      - name: Rename Build Directory
+        run: |
+          mkdir artifacts
+          mv docs/_build/html artifacts/${{ inputs.tag }}
+
+      - name: Upload Docs Artifact
+        uses: actions/upload-artifact@v4.4.3
+        with:
+          name: docs-${{ inputs.tag }}
+          path: artifacts
diff --git a/.github/workflows/_build_legacy_docs.yaml b/.github/workflows/_build_legacy_docs.yaml
@@ -0,0 +1,61 @@
+on:
+  workflow_call:
+    inputs:
+      tag:
+        type: string
+        description: A tag for the docs artifact
+        required: true
+
+jobs:
+  build_legacy_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PtyPy Code
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+          check-latest: true
+
+      - name: Setup MPI
+        uses: mpi4py/setup-mpi@v1
+        with:
+          mpi: mpich
+
+      - name: Install Sphinx
+        run: pip install sphinx
+
+      - name: Install PtyPy
+        run: pip install .[full]
+
+      - name: Prepare Tutorials
+        working-directory: doc
+        run: python script2rst.py
+
+      - name: Prepare Templates
+        working-directory: doc
+        run: python tmp2rst.py
+
+      - name: Prepare Parameters
+        working-directory: doc
+        run: python parameters2rst.py
+
+      - name: Set Path to Sphinx Build
+        run: echo "SPHINXBUILD=`which sphinx-build`" >> $GITHUB_ENV
+
+      - name: Build Sphinx Documentation
+        working-directory: doc
+        run: make html
+
+      - name: Rename Build Directory
+        run: |
+          mkdir artifacts
+          mv doc/build/html artifacts/${{ inputs.tag }}
+
+      - name: Upload Docs Artifact
+        uses: actions/upload-artifact@v4.4.3
+        with:
+          name: docs-${{ inputs.tag }}
+          path: artifacts
diff --git a/.github/workflows/_github_pages.yaml b/.github/workflows/_github_pages.yaml
@@ -0,0 +1,35 @@
+on:
+  workflow_call:
+
+jobs:
+  publish_pages:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Setup Pages
+        uses: actions/configure-pages@v5.0.0
+
+      - name: Download All Docs Artifact
+        uses: actions/download-artifact@v4.1.8
+        with:
+          pattern: docs-*
+          merge-multiple: true
+          path: ./
+
+      - name: Fix File Permissions for Pages
+        run: |
+          chmod -R +rX .
+
+      - name: Upload Merged Artifact to Pages
+        uses: actions/upload-pages-artifact@v3.0.1
+        with:
+          path: ./
+
+      - name: Publish Docs to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4.0.5
diff --git a/.github/workflows/_switcher.yaml b/.github/workflows/_switcher.yaml
@@ -0,0 +1,32 @@
+on:
+  workflow_call:
+
+jobs:
+  version_switcher:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PtyPy Code
+        uses: actions/checkout@v4
+
+      - name: Upload index.html as Artifact
+        uses: actions/upload-artifact@v4.4.3
+        with:
+          name: docs-index-html
+          path: .github/pages/index.html
+
+      - name: Download All Docs Artifact
+        uses: actions/download-artifact@v4.1.8
+        with:
+          pattern: docs-*
+          merge-multiple: true
+          path: ./doc_versions
+
+      - name: Create Switcher File
+        run: python .github/pages/switcher.py ./doc_versions ${{ github.repository }} .github/pages/switcher.json
+
+      - name: Upload switcher.json as Artifact
+        uses: actions/upload-artifact@v4.4.3
+        with:
+          name: docs-switcher-json
+          path: .github/pages/switcher.json
+
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -0,0 +1,30 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+      - dev
+  release:
+    type: [published]
+
+jobs:
+  legacy_docs:
+    uses: ./.github/workflows/_build_legacy_docs.yaml
+    with: 
+      tag: legacy
+
+  new_docs:
+    uses: ./.github/workflows/_build_docs.yaml
+    with:
+      tag: ${{ github.ref_name }}
+
+  switcher:
+    uses: ./.github/workflows/_switcher.yaml
+    needs:
+      - legacy_docs
+      - new_docs
+
+  github_pages:
+    needs: switcher
+    uses: ./.github/workflows/_github_pages.yaml
diff --git a/.github/workflows/test.yml → .github/workflows/tests.yaml b/.github/workflows/test.yml → .github/workflows/tests.yaml
@@ -6,11 +6,16 @@ on:
   push:
     branches:
       - master
+    paths-ignore:
+      - "docs/**"
+      - ".github/workflows/**"
   pull_request:
     branches:
       - master
       - dev
       - hotfixes
+    paths-ignore:
+      - "docs/**"
   # Also trigger on page_build, as well as release created events
   page_build:
   release:

diff --git a/.gitignore b/.gitignore
@@ -29,3 +29,5 @@ ghostdriver*
 .ipynb_checkpoints
 .clang-format
 pip-wheel-metadata/
+.venv/
+docs/_build
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,3 @@
+source/reference/generated/
+source/parameters/generated/
+_build/
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# 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/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1 @@
+pydata-sphinx-theme