Deploy documentation with GitHub Pages

.github/workflows/docs.yml

@@ -25,7 +25,7 @@ permissions:
 
 concurrency:
   group: docs-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name != 'workflow_dispatch' }}
+  cancel-in-progress: false
 
 jobs:
   build:
@@ -40,15 +40,32 @@ jobs:
           cache: pip
       - name: Install documentation dependencies
         run: python -m pip install -e ".[docs]"
-      - name: Build documentation artifact
+      - name: Build GitHub Pages artifact
         run: python scripts/build_docs.py --output-dir build/web-docs
       - name: Run documentation policy tests
         run: python -m pytest tests/test_web_docs.py -q
-      - name: Upload documentation artifact
-        uses: actions/upload-artifact@v7
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v5
         with:
-          name: web-docs-${{ github.sha }}
           path: build/web-docs
           include-hidden-files: true
-          if-no-files-found: error
-          retention-days: 7
+
+  deploy:
+    name: Deploy GitHub Pages
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v6
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

README.md

@@ -2,9 +2,9 @@
 
 Headless Python package for generating and computing training observables.
 
-The source checkout includes the current
-[API reference](https://github.com/MetaCircleAI/Observable-Library/blob/main/docs/api.md)
-and a [practical usage guide](https://github.com/MetaCircleAI/Observable-Library/blob/main/docs/usage.md).
+The documentation site includes the current
+[API reference](https://metacircleai.github.io/Observable-Library/api.html)
+and a [practical usage guide](https://metacircleai.github.io/Observable-Library/usage.html).
 
 Core boundary:
 
@@ -143,7 +143,7 @@ source.detach()
   id and step readback only; there is no lookup by display name, source, or
   reduction.
 - The current public contract supports only `selector="all"`. See the
-  [practical usage guide](https://github.com/MetaCircleAI/Observable-Library/blob/main/docs/usage.md)
+  [practical usage guide](https://metacircleai.github.io/Observable-Library/usage.html)
   for hook lifetime, source freshness, custom observable, transform, filter,
   and identity details.
 

docs/conf.py

@@ -37,6 +37,7 @@
 
 html_theme = "pydata_sphinx_theme"
 html_title = f"{project} {version}"
+html_baseurl = "https://metacircleai.github.io/Observable-Library/"
 templates_path = ["_templates"]
 html_static_path = ["_static"]
 html_css_files = ["css/tokens.css", "css/site.css"]

pyproject.toml

@@ -15,7 +15,7 @@ authors = [{name = "Jinxin"}]
 
 [project.urls]
 Homepage = "https://github.com/MetaCircleAI/Observable-Library"
-Documentation = "https://github.com/MetaCircleAI/Observable-Library/blob/main/docs/api.md"
+Documentation = "https://metacircleai.github.io/Observable-Library/"
 Repository = "https://github.com/MetaCircleAI/Observable-Library"
 Issues = "https://github.com/MetaCircleAI/Observable-Library/issues"
 

tests/test_docs_and_examples.py

@@ -87,19 +87,21 @@ def test_readme_quickstart_prints_and_reads_back_a_stored_observation(
     assert str(namespace["stored_value"]) in output
 
 
-def test_readme_links_to_canonical_api_and_shipped_examples() -> None:
+def test_readme_links_to_canonical_docs_and_shipped_examples() -> None:
     readme = README.read_text(encoding="utf-8")
-    base_url = "https://github.com/MetaCircleAI/Observable-Library/blob/main/"
 
-    paths = [
-        "docs/api.md",
-        "docs/usage.md",
+    docs_url = "https://metacircleai.github.io/Observable-Library/"
+    for path in ["api.html", "usage.html"]:
+        assert f"{docs_url}{path}" in readme
+
+    source_url = "https://github.com/MetaCircleAI/Observable-Library/blob/main/"
+    example_paths = [
         *(f"examples/{path.name}" for path in ONLINE_EXAMPLES),
         ADVANCED_ONLINE_EXAMPLE.relative_to(ROOT).as_posix(),
         OFFLINE_EXAMPLE.relative_to(ROOT).as_posix(),
     ]
-    for path in paths:
-        assert f"{base_url}{path}" in readme
+    for path in example_paths:
+        assert f"{source_url}{path}" in readme
 
 
 def test_readme_states_the_exact_local_storage_boundary() -> None:

tests/test_package_metadata.py

@@ -57,7 +57,7 @@ def test_pyproject_declares_canonical_project_urls() -> None:
 
     assert metadata["project"]["urls"] == {
         "Homepage": "https://github.com/MetaCircleAI/Observable-Library",
-        "Documentation": "https://github.com/MetaCircleAI/Observable-Library/blob/main/docs/api.md",
+        "Documentation": "https://metacircleai.github.io/Observable-Library/",
         "Repository": "https://github.com/MetaCircleAI/Observable-Library",
         "Issues": "https://github.com/MetaCircleAI/Observable-Library/issues",
     }

tests/test_web_docs.py

@@ -62,6 +62,12 @@ def test_build_site_creates_one_documentation_artifact(tmp_path: Path) -> None:
         assert (output_dir / relative).is_file()
 
 
+def test_docs_config_uses_the_github_pages_url() -> None:
+    conf = (DOCS / "conf.py").read_text(encoding="utf-8")
+
+    assert 'html_baseurl = "https://metacircleai.github.io/Observable-Library/"' in conf
+
+
 def test_web_docs_have_the_complete_top_level_navigation() -> None:
     assert all(path.is_file() for path in WEB_DOCS)
     index = (DOCS / "index.md").read_text(encoding="utf-8")