diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml index f6b361836..756980b9c 100644 --- a/.github/workflows/docs-preview.yml +++ b/.github/workflows/docs-preview.yml @@ -3,7 +3,7 @@ name: Build and preview docs on: push: branches-ignore: - - 'main' + - "main" tags-ignore: - v* pull_request: @@ -19,25 +19,30 @@ jobs: build-docs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v6 - with: - fetch-depth: 0 - - uses: actions/setup-python@v6 - with: - python-version-file: "pyproject.toml" - - - name: Install uv - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0 - - - name: Install Python dependencies - run: | - uv sync --locked --extra docs - - - name: Test build docs - run: | - uv run make -C docs/ local - - - uses: rossjrw/pr-preview-action@v1 - with: - source-dir: docs/_build/dev - if: github.event_name == 'pull_request' + - uses: actions/checkout@v6 + with: + fetch-depth: 0 + + - uses: actions/setup-python@v6 + if: github.event.action != 'closed' # We don't need the build if we know the preview will be removed + with: + python-version-file: "pyproject.toml" + + - name: Install uv + if: github.event.action != 'closed' # We don't need the build if we know the preview will be removed + uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0 + + - name: Install Python dependencies + if: github.event.action != 'closed' # We don't need the build if we know the preview will be removed + run: | + uv sync --locked --extra docs + + - name: Test build docs + if: github.event.action != 'closed' # We don't need the build if we know the preview will be removed + run: | + uv run make -C docs/ local + + - uses: rossjrw/pr-preview-action@v1 + with: + source-dir: docs/_build/dev + if: github.event_name == 'pull_request' diff --git a/docs/conf.py b/docs/conf.py index 703e86140..cab9cfe9c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,25 +34,11 @@ # process the loaded version information as you wish html_context = globals().get("html_context", {}) - tag_revisions = [ - rev - for rev in html_context["revisions"] - if rev.type_ == GitRefType.TAG and rev.name.startswith("v") - ] - - latest = sorted(tag_revisions, key=lambda x: x.name)[ - -1 - ] # latest by version - if ( html_context["current"].type_ == GitRefType.BRANCH and html_context["current"].name == "main" ): - major, minor, revision = latest.name.split("v")[-1].split( - "." - ) # get version number from tag name - next_dev_version = f"{major}.{minor}.{int(revision) + 1}.dev0" - release = next_dev_version + release = os.getenv("SETUPTOOLS_SCM_PRETEND_VERSION_FOR_JULEARN") else: release = html_context["current"].name diff --git a/docs/poly.py b/docs/poly.py index 7ddfcc70d..cf9f25141 100644 --- a/docs/poly.py +++ b/docs/poly.py @@ -18,7 +18,7 @@ ) from sphinx_polyversion.pyvenv import Pip from sphinx_polyversion.setuptools_scm import SetuptoolsScmDriver -from sphinx_polyversion.sphinx import SphinxBuilder +from sphinx_polyversion.sphinx import Placeholder, SphinxBuilder #: Regex matching the branches to build docs for @@ -69,9 +69,16 @@ logger.info(f"Docs Source directory: {docs_src}") logger.info(f"Output directory: {out_dir}") + +# Command to ensure that the output directory is clean before building +# (otherswise old files may remain if they were removed in the new version). +pre_cmd = ["rm", "-r", Placeholder.OUTPUT_DIR] + # Builders by version: BUILDER = { - None: SphinxBuilder(docs_src, args=SPHINX_ARGS.split()), # default + None: SphinxBuilder( + docs_src, args=SPHINX_ARGS.split(), pre_cmd=pre_cmd + ), # default } @@ -311,6 +318,7 @@ def closest_tag(ref, tags) -> "str | None": logger.info(f"Updated TAG_REGEX to: {TAG_REGEX}") +# #: Data passed to templates def data(driver, rev, env): """Create a factory for data passed to templates. @@ -362,7 +370,7 @@ def root_data(driver): # static_dir=static_dir, data_factory=data, root_data_factory=root_data, -).run() +).run(sequential=SEQUENTIAL) if NO_PATCH: logger.info("NO_PATCH is set, skipping HTML patching.") @@ -538,13 +546,11 @@ def ensure_css_link(directory: Path): if built_dir.is_dir(): if built_dir.name.startswith("v"): logger.info(f"Patching built version directory: {built_dir.name}") - current_version = next( - [ - tag - for tag in built_versions["tags"] - if tag.name == built_dir.name - ] - ) + current_version = [ # noqa: RUF015 + tag + for tag in built_versions["tags"] + if tag.name == built_dir.name + ][0] if int(built_dir.name.split(".")[1]) < 3: # Old read_the_docs template version_rtd_html = versions_rtd_template.render(