From 6ba0e511ffa87d7d39c01022670a89ba95ae90f1 Mon Sep 17 00:00:00 2001 From: "python-templates-copier-update[bot]" Date: Sun, 11 Oct 2026 11:26:47 +0000 Subject: [PATCH 1/3] Update from Copier (2026-10-11T11-26-44Z) Signed-off-by: python-templates-copier-update[bot] --- .copier-answers.yaml | 2 +- .github/workflows/build.yaml | 2 +- Makefile | 10 +++++----- pyproject.toml | 3 ++- 4 files changed, 9 insertions(+), 8 deletions(-) diff --git a/.copier-answers.yaml b/.copier-answers.yaml index 44d66b16..6a909f2e 100644 --- a/.copier-answers.yaml +++ b/.copier-answers.yaml @@ -1,5 +1,5 @@ # Changes here will be overwritten by Copier -_commit: ebb6e1c +_commit: '4372075' _src_path: https://github.com/python-project-templates/base.git add_docs: false add_extension: python diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index f92bd2bd..b6e816d5 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -15,7 +15,7 @@ on: workflow_dispatch: concurrency: - group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true permissions: diff --git a/Makefile b/Makefile index ac6be824..8aa5caf3 100644 --- a/Makefile +++ b/Makefile @@ -25,16 +25,16 @@ lint-py: ## lint python with ruff python -m ruff format --check yardang lint-docs: ## lint docs with mdformat and codespell - python -m mdformat --check README.md - python -m codespell_lib README.md + python -m mdformat --check README.md $(wildcard docs/src) + python -m codespell_lib README.md $(wildcard docs/src) fix-py: ## autoformat python code with ruff python -m ruff check --fix yardang python -m ruff format yardang fix-docs: ## autoformat docs with mdformat and codespell - python -m mdformat README.md - python -m codespell_lib --write README.md + python -m mdformat README.md $(wildcard docs/src) + python -m codespell_lib --write README.md $(wildcard docs/src) lint: lint-py lint-docs ## run all linters lints: lint @@ -52,7 +52,7 @@ check-dist: ## check python sdist and wheel with check-dist check-types: ## check python types with ty ty check --python $$(which python) -checks: check-dist +checks: check-dist check-types # Alias check: checks diff --git a/pyproject.toml b/pyproject.toml index 23027440..05a9737a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -73,6 +73,7 @@ develop = [ "codespell", "hatchling", "mdformat", + "mdformat-frontmatter", "mdformat-tables>=1", "pytest", "pytest-cov", @@ -117,7 +118,7 @@ replace = 'version = "{new_version}"' [tool.coverage.run] branch = true omit = [ - "yardang/tests/integration/", + "yardang/tests/integration/*", ] [tool.coverage.report] From 6fed490326099d86457e2c651830570b7a30fe2a Mon Sep 17 00:00:00 2001 From: Tim Paine <3105306+timkpaine@users.noreply.github.com> Date: Sun, 11 Oct 2026 10:58:07 -0400 Subject: [PATCH 2/3] Format documentation and correct build annotations Signed-off-by: Tim Paine <3105306+timkpaine@users.noreply.github.com> --- Makefile | 8 +++---- docs/src/api.md | 1 - docs/src/configuration.md | 44 ++++++++++++++++++------------------ docs/src/home.md | 5 +--- yardang/build.py | 32 +++++++++++++------------- yardang/cli.py | 8 +++---- yardang/sphinx/llms.py | 4 +++- yardang/tests/test_sphinx.py | 2 ++ yardang/wiki.py | 2 +- 9 files changed, 53 insertions(+), 53 deletions(-) diff --git a/Makefile b/Makefile index 8aa5caf3..05e115eb 100644 --- a/Makefile +++ b/Makefile @@ -25,16 +25,16 @@ lint-py: ## lint python with ruff python -m ruff format --check yardang lint-docs: ## lint docs with mdformat and codespell - python -m mdformat --check README.md $(wildcard docs/src) - python -m codespell_lib README.md $(wildcard docs/src) + python -m mdformat --check README.md $(wildcard docs/src) + python -m codespell_lib README.md $(wildcard docs/src) fix-py: ## autoformat python code with ruff python -m ruff check --fix yardang python -m ruff format yardang fix-docs: ## autoformat docs with mdformat and codespell - python -m mdformat README.md $(wildcard docs/src) - python -m codespell_lib --write README.md $(wildcard docs/src) + python -m mdformat README.md $(wildcard docs/src) + python -m codespell_lib --write README.md $(wildcard docs/src) lint: lint-py lint-docs ## run all linters lints: lint diff --git a/docs/src/api.md b/docs/src/api.md index f21f8337..5a268f23 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -118,4 +118,3 @@ Use `js:autoclass` to document classes: :members: ``` - diff --git a/docs/src/configuration.md b/docs/src/configuration.md index d1b1ed3b..5ccf666f 100644 --- a/docs/src/configuration.md +++ b/docs/src/configuration.md @@ -16,6 +16,7 @@ pages = [ ] use-autoapi = true ``` + ## [`name`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-project) The project name is taken from the standard section, or from the `cwd`. @@ -101,22 +102,22 @@ theme = "fuma" html_theme_options = { github_url = "https://github.com/you/project", toc_style = "clerk" } ``` -| Option | Default | Description | -| --- | --- | --- | -| `layout` | `docs` | `docs` puts the header beside the sidebar; `notebook` spans it across the top. | -| `toc_style` | `normal` | `clerk` dims headings away from the current one. | -| `color_preset` | `neutral` | Accent colour: `neutral`, `amber`, `blue`, `emerald`, `purple`, `rose`. | -| `fonts` | `bundled` | `system` skips the bundled webfonts and uses the system stack. | -| `search` | `true` | Enables the search dialog and its index. | -| `sidebar_hide_name` | `false` | Hides the project name next to the logo. | -| `default_open_level` | `1` | Sidebar folder depth expanded by default. | -| `github_url` | — | Adds a GitHub link, and an "Edit this page" link. | -| `edit_page_url_template` | — | Overrides the edit link, e.g. `https://host/edit/main/{filename}`. | -| `nav_links` | — | Header links, as `[{title, url}]` or `"Title\|url, Title\|url"`. | -| `sidebar_tabs` | — | Navigator entries under the search box, as `[{title, url, description, icon, match}]`. | -| `announcement` | — | Banner text shown above the header. | -| `footer_text` | — | Extra line in the footer. | -| `light_css_variables` / `dark_css_variables` | — | CSS custom property overrides, e.g. `{ "color-fd-primary" = "#e11d48" }`. | +| Option | Default | Description | +| -------------------------------------------- | --------- | -------------------------------------------------------------------------------------- | +| `layout` | `docs` | `docs` puts the header beside the sidebar; `notebook` spans it across the top. | +| `toc_style` | `normal` | `clerk` dims headings away from the current one. | +| `color_preset` | `neutral` | Accent colour: `neutral`, `amber`, `blue`, `emerald`, `purple`, `rose`. | +| `fonts` | `bundled` | `system` skips the bundled webfonts and uses the system stack. | +| `search` | `true` | Enables the search dialog and its index. | +| `sidebar_hide_name` | `false` | Hides the project name next to the logo. | +| `default_open_level` | `1` | Sidebar folder depth expanded by default. | +| `github_url` | — | Adds a GitHub link, and an "Edit this page" link. | +| `edit_page_url_template` | — | Overrides the edit link, e.g. `https://host/edit/main/{filename}`. | +| `nav_links` | — | Header links, as `[{title, url}]` or `"Title\|url, Title\|url"`. | +| `sidebar_tabs` | — | Navigator entries under the search box, as `[{title, url, description, icon, match}]`. | +| `announcement` | — | Banner text shown above the header. | +| `footer_text` | — | Extra line in the footer. | +| `light_css_variables` / `dark_css_variables` | — | CSS custom property overrides, e.g. `{ "color-fd-primary" = "#e11d48" }`. | #### Content components @@ -400,7 +401,6 @@ language = "en" pygments_style = "sphinx" ``` - ## [Myst](https://myst-parser.readthedocs.io/en/latest/#) ```toml @@ -531,7 +531,6 @@ mindmap Mermaid ``` - ## GitHub Admonitions GitHub admonitions are automatically translated to sphinx. @@ -835,7 +834,7 @@ rustdoc-fmt = { mylib-utils = "rst" } The pages are generated for you, so your documentation files only need a toctree entry pointing at them: -````markdown +```markdown # API Reference \`\`\`{toctree} @@ -844,7 +843,7 @@ The pages are generated for you, so your documentation files only need a toctree /api/mylib/lib /api/mylib-utils/lib \`\`\` -```` +``` ## Sphinx-JS Integration @@ -941,7 +940,7 @@ ts-type-bold = true Then in your documentation files, you can use sphinx-js directives: -````markdown +```markdown # API Reference ## Functions @@ -959,7 +958,7 @@ Then in your documentation files, you can use sphinx-js directives: \`\`\`{js:automodule} myModule \`\`\` -```` +``` ## GitHub Wiki Integration @@ -1123,6 +1122,7 @@ git push ``` The generated wiki includes: + - `Home.md` - The main landing page (converted from index.md) - `_Sidebar.md` - Navigation sidebar with links to all pages - `_Footer.md` - Footer with links to documentation and repository diff --git a/docs/src/home.md b/docs/src/home.md index 6c1a8293..84db071e 100644 --- a/docs/src/home.md +++ b/docs/src/home.md @@ -1,5 +1,3 @@ - -
yardang

yardang

@@ -15,7 +13,6 @@ [`yardang`](https://www.britannica.com/science/yardang) makes building [Sphinx](https://www.sphinx-doc.org/en/master/) easy. - ::::{grid} 1 2 2 2 :margin: 4 4 0 0 :gutter: 1 @@ -49,6 +46,6 @@ Star, Fork, or contribute on GitHub. ::: :::: -------------- +______________________________________________________________________ *This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base).* diff --git a/yardang/build.py b/yardang/build.py index 49e2ec14..43f348f6 100644 --- a/yardang/build.py +++ b/yardang/build.py @@ -298,8 +298,8 @@ def customize(args): custom_css = custom_css if custom_css is not None else get_config_flex(section="custom-css", base=config_base) custom_js = custom_js if custom_js is not None else get_config_flex(section="custom-js", base=config_base) assets_dir = Path(__file__).parent - custom_css = _resolve_custom_asset(custom_css, theme, "css", assets_dir=assets_dir) - custom_js = _resolve_custom_asset(custom_js, theme, "js", assets_dir=assets_dir) + custom_css_content = _resolve_custom_asset(custom_css, theme, "css", assets_dir=assets_dir) + custom_js_content = _resolve_custom_asset(custom_js, theme, "js", assets_dir=assets_dir) source_dir = source_dir or get_config_flex(section="source-dir", base=config_base) existing_source = source_dir is not None @@ -635,10 +635,10 @@ def customize(args): html_output = Path(html_output_dir) if html_output_dir is not None else Path("docs/html") styles_dir = html_output / "_static" / "styles" styles_dir.mkdir(parents=True, exist_ok=True) - (styles_dir / "custom.css").write_text(custom_css or "") + (styles_dir / "custom.css").write_text(custom_css_content or "") js_dir = html_output / "_static" / "js" js_dir.mkdir(parents=True, exist_ok=True) - (js_dir / "custom.js").write_text(custom_js or "") + (js_dir / "custom.js").write_text(custom_js_content or "") # append docs-specific ignores to gitignore if not existing_source and Path(".gitignore").exists(): @@ -665,23 +665,23 @@ def customize(args): @contextmanager def generate_wiki_configuration( *, - project: str = "", - title: str = "", - module: str = "", - description: str = "", - author: str = "", - copyright: str = "", - version: str = "", - theme: str = "furo", - docs_root: str = "", - root: str = "", - cname: str = "", + project: str | None = "", + title: str | None = "", + module: str | None = "", + description: str | None = "", + author: str | None = "", + copyright: str | None = "", + version: str | None = "", + theme: str | None = "furo", + docs_root: str | None = "", + root: str | None = "", + cname: str | None = "", pages: list | None = None, use_autoapi: bool | None = None, autoapi_ignore: list | None = None, custom_css: Path | None = None, custom_js: Path | None = None, - config_base: str = "tool.yardang", + config_base: str | None = "tool.yardang", previous_versions: bool | None = False, adjust_arguments: Callable | None = None, adjust_template: Callable | None = None, diff --git a/yardang/cli.py b/yardang/cli.py index 15157c4f..494fdd42 100644 --- a/yardang/cli.py +++ b/yardang/cli.py @@ -72,9 +72,9 @@ def build( sleep(0.1) if process.returncode != 0: if pdb: - import pdb # noqa: T100 + import pdb as debugger # noqa: T100 - pdb.set_trace() # noqa: T100 + debugger.set_trace() # noqa: T100 raise Exit(process.returncode) @@ -170,9 +170,9 @@ def wiki( sleep(0.1) if process.returncode != 0: if pdb: - import pdb # noqa: T100 + import pdb as debugger # noqa: T100 - pdb.set_trace() # noqa: T100 + debugger.set_trace() # noqa: T100 raise Exit(process.returncode) # Post-process for GitHub Wiki compatibility diff --git a/yardang/sphinx/llms.py b/yardang/sphinx/llms.py index dfd9fd28..c770f759 100644 --- a/yardang/sphinx/llms.py +++ b/yardang/sphinx/llms.py @@ -1,8 +1,10 @@ from pathlib import Path +from typing import cast from urllib.parse import urlsplit, urlunsplit from docutils import nodes from sphinx.application import Sphinx +from sphinx.builders import Builder from sphinx_markdown_builder.builder import MarkdownBuilder from sphinx_markdown_builder.translator import MarkdownTranslator @@ -42,7 +44,7 @@ def __init__(self, app: Sphinx): self.current_doc_name = "" def create_translator(self, *args): - return self.app.registry.create_translator(self, *args) + return self.app.registry.create_translator(cast(Builder, self), *args) @staticmethod def get_target_uri(docname: str, typ: str | None = None) -> str: diff --git a/yardang/tests/test_sphinx.py b/yardang/tests/test_sphinx.py index d1c19fc2..ea6e7fd6 100644 --- a/yardang/tests/test_sphinx.py +++ b/yardang/tests/test_sphinx.py @@ -32,6 +32,8 @@ def test_github_admonition_preserves_quoted_blank_lines(tmp_path, monkeypatch): with generate_docs_configuration() as conf_dir: spec = importlib.util.spec_from_file_location("yardang_test_conf", Path(conf_dir) / "conf.py") + assert spec is not None + assert spec.loader is not None conf = importlib.util.module_from_spec(spec) spec.loader.exec_module(conf) diff --git a/yardang/wiki.py b/yardang/wiki.py index 1568bbb0..de787522 100644 --- a/yardang/wiki.py +++ b/yardang/wiki.py @@ -452,7 +452,7 @@ def _is_api_page(filename: str, content: str) -> bool: return indicator_count >= 2 -def extract_toctree_entries(content: str) -> list[tuple[str, str]]: +def extract_toctree_entries(content: str) -> list[tuple[str | None, str]]: """Extract toctree entries from markdown content. Parses MyST-style toctree directives to find linked pages. From f18935b532c45425a1a484d17a5df1f88bbce9d3 Mon Sep 17 00:00:00 2001 From: Tim Paine <3105306+timkpaine@users.noreply.github.com> Date: Sun, 11 Oct 2026 11:04:12 -0400 Subject: [PATCH 3/3] Cover Wiki debugging and HTML Markdown rendering Signed-off-by: Tim Paine <3105306+timkpaine@users.noreply.github.com> --- yardang/tests/test_all.py | 7 ++++--- yardang/tests/test_llms.py | 5 +++-- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/yardang/tests/test_all.py b/yardang/tests/test_all.py index b4921632..a1f4b52a 100644 --- a/yardang/tests/test_all.py +++ b/yardang/tests/test_all.py @@ -5,7 +5,7 @@ from typer import Exit from yardang.build import generate_docs_configuration -from yardang.cli import build, debug +from yardang.cli import build, debug, wiki from yardang.utils import get_config_flex @@ -19,7 +19,8 @@ def test_cli(): debug() -def test_cli_pdb_on_failure(monkeypatch): +@pytest.mark.parametrize("command", [build, wiki]) +def test_cli_pdb_on_failure(monkeypatch, command): class FailedProcess: returncode = 1 @@ -32,7 +33,7 @@ def poll(): monkeypatch.setattr("pdb.set_trace", lambda: traced.append(True)) with pytest.raises(Exit): - build(pdb=True) + command(pdb=True) assert traced == [True] diff --git a/yardang/tests/test_llms.py b/yardang/tests/test_llms.py index 90cc0ced..4f422f0e 100644 --- a/yardang/tests/test_llms.py +++ b/yardang/tests/test_llms.py @@ -136,13 +136,14 @@ def test_full_build_can_be_disabled(tmp_path, monkeypatch): assert "llms-full.txt" not in (output / "llms.txt").read_text() -def test_explicit_builder_copies_downloads(tmp_path, monkeypatch): +@pytest.mark.parametrize("builder", ["html", "yardang-llms"]) +def test_llms_builders_copy_downloads(tmp_path, monkeypatch, builder): _write_project(tmp_path) monkeypatch.chdir(tmp_path) output = tmp_path / "llms" with generate_docs_configuration() as conf_dir: - result = build_main(["-q", "-b", "yardang-llms", "-c", str(conf_dir), ".", str(output)]) + result = build_main(["-q", "-b", builder, "-c", str(conf_dir), ".", str(output)]) assert result == 0 download = re.search(r"\]\(([^)]*_downloads/[^)]+)\)", (output / "index.html.md").read_text())