diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index da2a59e..a4d781b 100644 --- a/.github/workflows/docs.yml +++ b/.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 diff --git a/README.md b/README.md index d7487d7..fe253b3 100644 --- a/README.md +++ b/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. diff --git a/docs/conf.py b/docs/conf.py index bd51a15..e433055 100644 --- a/docs/conf.py +++ b/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"] diff --git a/pyproject.toml b/pyproject.toml index 019b406..c3e515e 100644 --- a/pyproject.toml +++ b/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" diff --git a/tests/test_docs_and_examples.py b/tests/test_docs_and_examples.py index c88ab5e..0fdea27 100644 --- a/tests/test_docs_and_examples.py +++ b/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: diff --git a/tests/test_package_metadata.py b/tests/test_package_metadata.py index fb17c82..d3225db 100644 --- a/tests/test_package_metadata.py +++ b/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", } diff --git a/tests/test_web_docs.py b/tests/test_web_docs.py index de32af0..fc6aa79 100644 --- a/tests/test_web_docs.py +++ b/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")