Updates doc builder to use mkpages

[rsgalloway]

Replaces the local custom pages builder script with mkpages

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated no new comments.

Suppressed comments (11)

docs/examples/index.md:63

• Links to other docs pages use the ".md" source filename, but the mkpages navigation and pretty permalinks suggest these pages will be served at directory URLs (e.g. /api/). Linking to "../api.md" is likely to 404 on the published site; link to the pretty URL instead.

This issue also appears in the following locations of the same file:

• line 452
• line 457
  docs/examples/index.md:453

• This link uses the ".md" source filename; with mkpages/Jekyll pretty permalinks it will likely be published at "/overrides/". Consider linking to the pretty URL to avoid broken links.
  docs/examples/index.md:457
• This link uses the ".md" source filename; with mkpages/Jekyll pretty permalinks it will likely be published at "/distribution/". Consider linking to the pretty URL to avoid broken links.
  docs/examples/animation/index.md:28
• These GitHub and raw URLs hard-code the "master" branch. Since the Pages workflow also builds from "main", publishing from main would send readers to a different branch's files. Consider updating these links to use the publishing branch (e.g. main) to keep docs and examples in sync.
  docs/examples/vfx/index.md:28
• These GitHub and raw URLs hard-code the "master" branch. Since the Pages workflow also builds from "main", publishing from main would send readers to a different branch's files. Consider updating these links to use the publishing branch (e.g. main) to keep docs and examples in sync.
  docs/examples/data-pipeline/index.md:28
• These GitHub and raw URLs hard-code the "master" branch. Since the Pages workflow also builds from "main", publishing from main would send readers to a different branch's files. Consider updating these links to use the publishing branch (e.g. main) to keep docs and examples in sync.
  docs/examples/logs/index.md:28
• These GitHub and raw URLs hard-code the "master" branch. Since the Pages workflow also builds from "main", publishing from main would send readers to a different branch's files. Consider updating these links to use the publishing branch (e.g. main) to keep docs and examples in sync.
  docs/examples/ml-artifacts/index.md:28
• These GitHub and raw URLs hard-code the "master" branch. Since the Pages workflow also builds from "main", publishing from main would send readers to a different branch's files. Consider updating these links to use the publishing branch (e.g. main) to keep docs and examples in sync.
  docs/examples/overrides/index.md:17
• These GitHub links hard-code the "master" branch. Since the Pages workflow also builds from "main", publishing from main would send readers to a different branch's files. Consider updating these links to use the publishing branch (e.g. main) to keep docs and examples in sync.

This issue also appears on line 19 of the same file.
docs/examples/overrides/index.md:21

• These raw GitHub URLs hard-code the "master" branch. Since the Pages workflow also builds from "main", publishing from main would send readers to a different branch's files. Consider updating these links to use the publishing branch (e.g. main) to keep docs and examples in sync.
  pyproject.toml:42
• mkpages is now a required part of the publish-docs workflow, but it isn't version-pinned here while other dev tools (flake8/isort/black) are. Leaving it unpinned can make the docs build non-reproducible and can break Pages unexpectedly on new mkpages releases.

optional-dependencies = { dev = ["pytest", "flake8==7.1.1", "mccabe==0.7.0", "isort==5.13.2", "black==24.8.0", "mkpages"], test = ["pytest"] }

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated no new comments.

Suppressed comments (2)

pyproject.toml:42

• mkpages is now part of the docs publishing toolchain (used in CI), but it is unversioned while the other tooling dependencies here are pinned. This can make Pages builds non-reproducible and can break unexpectedly when mkpages releases a new version. Consider pinning or constraining mkpages (e.g., exact pin or a compatible range) the same way as flake8/isort/black.

optional-dependencies = { dev = ["pytest", "flake8==7.1.1", "mccabe==0.7.0", "isort==5.13.2", "black==24.8.0", "mkpages"], test = ["pytest"] }

.github/workflows/publish-docs.yml:42

• The step name still says "Build Jekyll source tree", but the implementation now uses mkpages. Renaming the step makes workflow logs clearer (and avoids confusion if mkpages fails).

      - name: Build Jekyll source tree
        run: |
          mkpages build docs/ --output _site_src