Skip to content

Add docs build CI workflow #5418

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mithr4ndir wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add docs build CI workflow #5418

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c6b59ca
Add docs build CI workflow
mithr4ndir Apr 7, 2026
e9af7a4
Apply review suggestions: remove uv pin, disable cache, add workflow …
mithr4ndir Apr 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions .github/workflows/docs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
name: Build Documentation

on:
push:
branches:
- main
paths:
- "doc/**"
- "pyproject.toml"
pull_request:
paths:
- "doc/**"
Comment thread
mithr4ndir marked this conversation as resolved.
workflow_dispatch:

permissions: {}

jobs:
build-docs:
name: Build Sphinx docs
runs-on: ubuntu-latest

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

env:
READTHEDOCS: "True"
Comment on lines +28 to +29
Copy link
Copy Markdown
Member

@neutrinoceros neutrinoceros Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this reads like we're trying to impressionate RTD. Is there a reason for doing this that I'm missing ?

Copy link
Copy Markdown
Author

@mithr4ndir mithr4ndir Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not trying to impersonate RTD. The https://github.com/yt-project/yt/blob/main/doc/Makefile#L49 checks that env var and skips sphinx-apidoc, which generates API stubs for every yt module. Those stubs cause autodoc to import the full package at build time, which can fail if compiled extensions or data aren't available. https://github.com/yt-project/yt/blob/main/doc/source/conf.py#L46 also uses it to skip autosummary and pythonscript_sphinxext (which executes inline Python scripts in the docs). It's saves time, and its avoiding build failures from operations that need a fully configured yt environment. Happy to use a different env var if you'd prefer

Copy link
Copy Markdown
Member

@neutrinoceros neutrinoceros Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks for the detailed explanation, I really had no idea this was the state of our setup


steps:
- name: Checkout repo
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false

- name: Set up uv
uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
with:
version: ">=0.9.11,<0.10.0"
Copy link
Copy Markdown
Member

@neutrinoceros neutrinoceros Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we don't pin uv anywhere else on CI, so I'd just remove this for consistency

Suggested change
version: ">=0.9.11,<0.10.0"

Copy link
Copy Markdown
Author

@mithr4ndir mithr4ndir Apr 7, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, I'll remove it. I matched it from https://github.com/yt-project/yt/blob/main/.github/workflows/build-test.yaml#L33 but happy to drop it here.

Copy link
Copy Markdown
Member

@neutrinoceros neutrinoceros Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh, weird. I don't remember writing this and don't really get why I would now. Thanks for pointing it out. I think we should remove the pin everywhere (but that other file is out of scope here)

python-version: "3.12"
prune-cache: false
Copy link
Copy Markdown
Member

@neutrinoceros neutrinoceros Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd rather we disable caching here for now.

Suggested change
prune-cache: false
enable-cache: false

Copy link
Copy Markdown
Author

@mithr4ndir mithr4ndir Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense, I'll apply your suggestion.


- name: Install pandoc
run: sudo apt-get update && sudo apt-get install -y pandoc
Comment thread
neutrinoceros marked this conversation as resolved.

- name: Install dependencies
run: uv sync --group=docs

- name: Build HTML docs
run: |
cd doc
uv run make html
Copy link
Copy Markdown
Member

@neutrinoceros neutrinoceros Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't look right. Where is that make python entry point supposed to come from ?

Copy link
Copy Markdown
Author

@mithr4ndir mithr4ndir Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

make is preinstalled on Ubuntu runners. The Makefile sets SPHINXBUILD = sphinx-build, so it needs sphinx-build on PATH. uv run handles that by prepending the venv's bin/ directory to PATH before executing the command, and child processes inherit it (https://docs.astral.sh/uv/concepts/projects/run/). Since we're setting READTHEDOCS=True (which skips sphinx-apidoc in the Makefile), we could also just call uv run sphinx-build -b html -d doc/build/doctrees doc/source doc/build/html directly if you'd prefer to skip make.

Copy link
Copy Markdown
Member

@neutrinoceros neutrinoceros Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The given command can be provided by the project environment or exist outside

oh, I was not aware uv run did this. It makes total sense now


- name: Upload built docs
uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
with:
name: yt-docs-html
path: doc/build/html/