From 23d6a3ef8afb0fddc0cc7c4591014b971ee2edf4 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Thu, 7 May 2026 08:48:02 +0300 Subject: docs: render llms.txt at build time (circinus) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Parity with [#1874](https://github.com/vyos/vyos-documentation/pull/1874) (current) and [#1876](https://github.com/vyos/vyos-documentation/pull/1876) (sagitta). Replaces the static `docs/_html_extra/llms.txt` with a Jinja template (`docs/_templates/llms.txt.j2`) rendered at build time via a `build-finished` hook in `conf.py`. URLs and the version line are interpolated from `html_baseurl` and `release`, so the rendered file always matches what circinus actually serves. Hook behavior matches `current`/`sagitta` exactly, including the two review-cycle hardenings landed on those PRs: - Skips on builders other than `html` and `readthedocs` — the curated template encodes `.html` URLs which don't match `dirhtml` output. - `RuntimeError` if `html_baseurl` is empty rather than silently rendering broken root-relative URLs. - Jinja `Environment(undefined=StrictUndefined)` so a typo in `llms.txt.j2` raises at build time instead of writing a half-blank `llms.txt`. The closed PR [#1875](https://github.com/vyos/vyos-documentation/pull/1875) was the previous attempt; this re-lands the change after the post-flip rebase situation cleared. Verified locally: hook tests (happy-path render, fail-fast on `html_baseurl=None`/`''`, `StrictUndefined` catches `{{ relase }}` typo, skips `dirhtml`, skips on build exception) pass against this worktree. \xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io) --- docs/_html_extra/llms.txt | 52 --------------------------------------------- docs/_templates/llms.txt.j2 | 52 +++++++++++++++++++++++++++++++++++++++++++++ docs/conf.py | 38 +++++++++++++++++++++++++++++++-- 3 files changed, 88 insertions(+), 54 deletions(-) delete mode 100644 docs/_html_extra/llms.txt create mode 100644 docs/_templates/llms.txt.j2 (limited to 'docs') diff --git a/docs/_html_extra/llms.txt b/docs/_html_extra/llms.txt deleted file mode 100644 index 03d8562d..00000000 --- a/docs/_html_extra/llms.txt +++ /dev/null @@ -1,52 +0,0 @@ -# VyOS - -> VyOS is a free, open-source network operating system based on Debian GNU/Linux. -> It provides routing, firewall, and VPN functionality via a unified CLI using -> `set`/`delete`/`show` command hierarchy. This documentation covers 1.5.x (circinus). - -VyOS configuration follows a tree structure. All configuration commands start with -`set` (to add/change) or `delete` (to remove). Changes are staged and applied with -`commit`. The CLI hierarchy maps directly to the documentation structure. - -## Quick Start - -- [Quick Start Guide](https://docs.vyos.io/en/1.5/quick-start.html): Minimal setup walkthrough -- [CLI Overview](https://docs.vyos.io/en/1.5/cli.html): Command-line interface usage - -## Configuration - -- [Firewall](https://docs.vyos.io/en/1.5/configuration/firewall/index.html): Zone-based firewall, rules, groups -- [Interfaces](https://docs.vyos.io/en/1.5/configuration/interfaces/index.html): Ethernet, bonding, bridge, VLAN, tunnel, wireless -- [Protocols](https://docs.vyos.io/en/1.5/configuration/protocols/index.html): BGP, OSPF, IS-IS, static routing, MPLS -- [VPN](https://docs.vyos.io/en/1.5/configuration/vpn/index.html): IPsec, OpenVPN, WireGuard, L2TP, PPTP -- [NAT](https://docs.vyos.io/en/1.5/configuration/nat/index.html): Source NAT, destination NAT, NAT66 -- [System](https://docs.vyos.io/en/1.5/configuration/system/index.html): DNS, NTP, syslog, users, task scheduler -- [High Availability](https://docs.vyos.io/en/1.5/configuration/highavailability/index.html): VRRP -- [Load Balancing](https://docs.vyos.io/en/1.5/configuration/loadbalancing/index.html): WAN and reverse proxy -- [Containers](https://docs.vyos.io/en/1.5/configuration/container/index.html): Podman-based container support -- [PKI](https://docs.vyos.io/en/1.5/configuration/pki/index.html): Certificate management -- [Policy](https://docs.vyos.io/en/1.5/configuration/policy/index.html): Route maps, prefix lists, access lists -- [Traffic Policy](https://docs.vyos.io/en/1.5/configuration/trafficpolicy/index.html): QoS and shaping -- [Service](https://docs.vyos.io/en/1.5/configuration/service/index.html): DHCP, DNS forwarding, SNMP, SSH, HTTPS API -- [VRF](https://docs.vyos.io/en/1.5/configuration/vrf/index.html): Virtual routing and forwarding - -## Operations - -- [Operational Commands](https://docs.vyos.io/en/1.5/operation/index.html): Show, monitor, restart commands - -## Installation - -- [Installation Guide](https://docs.vyos.io/en/1.5/installation/index.html): Bare metal, virtual, cloud deployments - -## Automation - -- [Automation](https://docs.vyos.io/en/1.5/automation/index.html): Ansible, Terraform, HTTP API, NETCONF - -## Configuration Examples - -- [Blueprints](https://docs.vyos.io/en/1.5/configexamples/index.html): Real-world topology examples - -## Optional - -- [Contributing](https://docs.vyos.io/en/1.5/contributing/index.html): Development workflow -- [VPP](https://docs.vyos.io/en/1.5/vpp/index.html): Vector Packet Processing integration diff --git a/docs/_templates/llms.txt.j2 b/docs/_templates/llms.txt.j2 new file mode 100644 index 00000000..db579e83 --- /dev/null +++ b/docs/_templates/llms.txt.j2 @@ -0,0 +1,52 @@ +# VyOS + +> VyOS is a free, open-source network operating system based on Debian GNU/Linux. +> It provides routing, firewall, and VPN functionality via a unified CLI using +> `set`/`delete`/`show` command hierarchy. This documentation covers {{ release }}. + +VyOS configuration follows a tree structure. All configuration commands start with +`set` (to add/change) or `delete` (to remove). Changes are staged and applied with +`commit`. The CLI hierarchy maps directly to the documentation structure. + +## Quick Start + +- [Quick Start Guide]({{ baseurl }}quick-start.html): Minimal setup walkthrough +- [CLI Overview]({{ baseurl }}cli.html): Command-line interface usage + +## Configuration + +- [Firewall]({{ baseurl }}configuration/firewall/index.html): Zone-based firewall, rules, groups +- [Interfaces]({{ baseurl }}configuration/interfaces/index.html): Ethernet, bonding, bridge, VLAN, tunnel, wireless +- [Protocols]({{ baseurl }}configuration/protocols/index.html): BGP, OSPF, IS-IS, static routing, MPLS +- [VPN]({{ baseurl }}configuration/vpn/index.html): IPsec, OpenVPN, WireGuard, L2TP, PPTP +- [NAT]({{ baseurl }}configuration/nat/index.html): Source NAT, destination NAT, NAT66 +- [System]({{ baseurl }}configuration/system/index.html): DNS, NTP, syslog, users, task scheduler +- [High Availability]({{ baseurl }}configuration/highavailability/index.html): VRRP +- [Load Balancing]({{ baseurl }}configuration/loadbalancing/index.html): WAN and reverse proxy +- [Containers]({{ baseurl }}configuration/container/index.html): Podman-based container support +- [PKI]({{ baseurl }}configuration/pki/index.html): Certificate management +- [Policy]({{ baseurl }}configuration/policy/index.html): Route maps, prefix lists, access lists +- [Traffic Policy]({{ baseurl }}configuration/trafficpolicy/index.html): QoS and shaping +- [Service]({{ baseurl }}configuration/service/index.html): DHCP, DNS forwarding, SNMP, SSH, HTTPS API +- [VRF]({{ baseurl }}configuration/vrf/index.html): Virtual routing and forwarding + +## Operations + +- [Operational Commands]({{ baseurl }}operation/index.html): Show, monitor, restart commands + +## Installation + +- [Installation Guide]({{ baseurl }}installation/index.html): Bare metal, virtual, cloud deployments + +## Automation + +- [Automation]({{ baseurl }}automation/index.html): Ansible, Terraform, HTTP API, NETCONF + +## Configuration Examples + +- [Blueprints]({{ baseurl }}configexamples/index.html): Real-world topology examples + +## Optional + +- [Contributing]({{ baseurl }}contributing/index.html): Development workflow +- [VPP]({{ baseurl }}vpp/index.html): Vector Packet Processing integration diff --git a/docs/conf.py b/docs/conf.py index 23c76d3e..ec95bf76 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -147,8 +147,10 @@ html_context = { # sphinx-sitemap: baseurl already includes /en/1.5/, so skip lang+version sitemap_url_scheme = '{link}' -# sphinx-llms-txt: disable auto-generated llms.txt, keep curated one from -# _html_extra; llms-full.txt is still auto-generated +# sphinx-llms-txt: disable the package's auto-generated index llms.txt. +# The curated llms.txt is rendered at build time from +# _templates/llms.txt.j2 by the _write_llms_txt() build-finished hook +# below; llms-full.txt is still auto-generated by sphinx-llms-txt. llms_txt_file = False # Custom sidebar templates, must be a dictionary that maps document names @@ -258,6 +260,38 @@ def _copy_md_sources(app, exception): shutil.copy2(path, dest) +def _write_llms_txt(app, exception): + # Skip dirhtml: the curated template encodes `.html` URLs (e.g. + # `quick-start.html`), which don't exist under `dirhtml` output + # (`quick-start/index.html`). Production publishes via the html / + # readthedocs builders, so dirhtml output would just be misleading. + if exception is not None or app.builder.name not in ( + 'html', 'readthedocs'): + return + if not app.config.html_baseurl: + # Fail loudly rather than rendering /quick-start.html etc. as a + # silently-broken root-relative URL — every supported branch + # sets html_baseurl, so a missing value is a regression. + raise RuntimeError( + 'html_baseurl must be set to render llms.txt') + from pathlib import Path + from jinja2 import Environment, StrictUndefined + tpl_path = Path(app.srcdir) / '_templates' / 'llms.txt.j2' + out_path = Path(app.outdir) / 'llms.txt' + baseurl = app.config.html_baseurl.rstrip('/') + '/' + # StrictUndefined: missing template variables raise rather than + # silently render as empty strings, so a typo in llms.txt.j2 fails + # the build instead of shipping a half-blank llms.txt. + env = Environment(undefined=StrictUndefined, keep_trailing_newline=True) + template = env.from_string(tpl_path.read_text(encoding='utf-8')) + rendered = template.render( + baseurl=baseurl, + release=app.config.release, + ) + out_path.write_text(rendered, encoding='utf-8') + + def setup(app): app.connect('builder-inited', _prefer_webp) app.connect('build-finished', _copy_md_sources) + app.connect('build-finished', _write_llms_txt) -- cgit v1.2.3 From 61496664110128dfa2969c80f67bbc9b8ab05c9c Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Thu, 7 May 2026 09:09:09 +0300 Subject: docs(conf.py): add docstring to _write_llms_txt hook Document the hook's purpose, inputs (`html_baseurl` + `release`), output (`/llms.txt`), and the division of labor with `sphinx_llms_txt` (which handles `llms-full.txt`). Also functions as a real-content nudge to GitHub's PR ref pipeline, which was failing to create `refs/pull/1903/head` after the initial empty-commit + close+reopen attempts. The substantive doc improvement is independently worthwhile. \xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io) --- docs/conf.py | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index ec95bf76..3550b37d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -261,6 +261,12 @@ def _copy_md_sources(app, exception): def _write_llms_txt(app, exception): + """Render the curated llms.txt at build-finished time. + + Reads ``_templates/llms.txt.j2``, interpolates ``html_baseurl`` and + ``release``, and writes ``/llms.txt``. ``llms-full.txt`` is + handled separately by the ``sphinx_llms_txt`` extension. + """ # Skip dirhtml: the curated template encodes `.html` URLs (e.g. # `quick-start.html`), which don't exist under `dirhtml` output # (`quick-start/index.html`). Production publishes via the html / -- cgit v1.2.3 From 1ce4a62f07759fc4bedd127236ef64110a1e8f89 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Thu, 7 May 2026 09:16:27 +0300 Subject: docs(conf.py): use FileSystemLoader/get_template for better tracebacks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Switch from `Environment.from_string(tpl_path.read_text(...))` to `Environment(loader=FileSystemLoader(...)).get_template('llms.txt.j2')`. When `StrictUndefined` raises on a typo in `llms.txt.j2` (e.g. `{{ relase }}`), the traceback now references the real template filename and line number instead of an anonymous in-memory template. That makes debugging template typos materially easier without changing any other behavior — same fail-fast guard, same trailing-newline handling, same rendered output. Same change applied symmetrically across [#1874](https://github.com/vyos/vyos-documentation/pull/1874) (current), [#1876](https://github.com/vyos/vyos-documentation/pull/1876) (sagitta), and [#1903](https://github.com/vyos/vyos-documentation/pull/1903) (circinus) so the hook stays identical across branches. Addresses CodeRabbit/Copilot review feedback on PR #1903. \xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io) --- docs/conf.py | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 3550b37d..cbe5fb67 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -281,15 +281,23 @@ def _write_llms_txt(app, exception): raise RuntimeError( 'html_baseurl must be set to render llms.txt') from pathlib import Path - from jinja2 import Environment, StrictUndefined - tpl_path = Path(app.srcdir) / '_templates' / 'llms.txt.j2' + from jinja2 import Environment, FileSystemLoader, StrictUndefined + tpl_dir = Path(app.srcdir) / '_templates' out_path = Path(app.outdir) / 'llms.txt' baseurl = app.config.html_baseurl.rstrip('/') + '/' - # StrictUndefined: missing template variables raise rather than - # silently render as empty strings, so a typo in llms.txt.j2 fails - # the build instead of shipping a half-blank llms.txt. - env = Environment(undefined=StrictUndefined, keep_trailing_newline=True) - template = env.from_string(tpl_path.read_text(encoding='utf-8')) + # FileSystemLoader + get_template (rather than from_string) makes + # Jinja tracebacks reference the real template filename and line + # number — useful when StrictUndefined trips on a typo in + # llms.txt.j2. StrictUndefined: missing template variables raise + # rather than silently render as empty strings, so a typo in + # llms.txt.j2 fails the build instead of shipping a half-blank + # llms.txt. + env = Environment( + loader=FileSystemLoader(str(tpl_dir)), + undefined=StrictUndefined, + keep_trailing_newline=True, + ) + template = env.get_template('llms.txt.j2') rendered = template.render( baseurl=baseurl, release=app.config.release, -- cgit v1.2.3 From a5b8e6fa6b6078e77bff329cac751c0b873f5f4b Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Thu, 7 May 2026 09:25:58 +0300 Subject: docs(conf.py): set Jinja autoescape=False explicitly for llms.txt template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The llms.txt template renders plain text (markdown), not HTML, so the HTML autoescape rules that bandit/ruff S701 flags don't apply. Explicit `autoescape=False` silences the lint while documenting the intent — there's no HTML context to escape into here. Behavior unchanged (Jinja's default `autoescape=False` was already in effect); this just makes it visible. Same change applied symmetrically across [#1874](https://github.com/vyos/vyos-documentation/pull/1874) (current), [#1876](https://github.com/vyos/vyos-documentation/pull/1876) (sagitta), and [#1903](https://github.com/vyos/vyos-documentation/pull/1903) (circinus). Addresses CodeRabbit review feedback (S701) on PR #1876. \xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io) --- docs/conf.py | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index cbe5fb67..26ce346c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -296,6 +296,10 @@ def _write_llms_txt(app, exception): loader=FileSystemLoader(str(tpl_dir)), undefined=StrictUndefined, keep_trailing_newline=True, + # Plain-text template (not HTML), so HTML autoescape is not + # appropriate. Setting autoescape=False explicitly to silence + # bandit/ruff S701 and document the intent. + autoescape=False, ) template = env.get_template('llms.txt.j2') rendered = template.render( -- cgit v1.2.3 From 98183560bd92e8a21d709ac78afe6497ae0d2042 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Thu, 7 May 2026 09:34:22 +0300 Subject: docs(llms.txt): point links at .md sources, not .html MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per the [llms.txt spec](https://llmstxt.org/), `/llms.txt` links should point at markdown files (the spec example: `[API docs](https://example.com/api.md)`). We were using `.html` URLs, which still work but force LLM consumers through HTML parsing for content that's already available as raw MyST at the same path (the `.md` is copied to HTML root by `_copy_md_sources`). Pivot the curated llms.txt template to `.md` URLs across all 22 entries. Spec-compliant, no extra requests, LLMs get raw markdown without the navigation chrome. Verified locally: `/en//.md` returns 200 with raw MyST content (frontmatter + body) for all linked paths on this branch. Same pivot applied symmetrically across [#1874](https://github.com/vyos/vyos-documentation/pull/1874) (current), [#1876](https://github.com/vyos/vyos-documentation/pull/1876) (sagitta), and [#1903](https://github.com/vyos/vyos-documentation/pull/1903) (circinus). 🤖 Generated by [robots](https://vyos.io) --- docs/_templates/llms.txt.j2 | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/_templates/llms.txt.j2 b/docs/_templates/llms.txt.j2 index db579e83..1c6a3900 100644 --- a/docs/_templates/llms.txt.j2 +++ b/docs/_templates/llms.txt.j2 @@ -10,43 +10,43 @@ VyOS configuration follows a tree structure. All configuration commands start wi ## Quick Start -- [Quick Start Guide]({{ baseurl }}quick-start.html): Minimal setup walkthrough -- [CLI Overview]({{ baseurl }}cli.html): Command-line interface usage +- [Quick Start Guide]({{ baseurl }}quick-start.md): Minimal setup walkthrough +- [CLI Overview]({{ baseurl }}cli.md): Command-line interface usage ## Configuration -- [Firewall]({{ baseurl }}configuration/firewall/index.html): Zone-based firewall, rules, groups -- [Interfaces]({{ baseurl }}configuration/interfaces/index.html): Ethernet, bonding, bridge, VLAN, tunnel, wireless -- [Protocols]({{ baseurl }}configuration/protocols/index.html): BGP, OSPF, IS-IS, static routing, MPLS -- [VPN]({{ baseurl }}configuration/vpn/index.html): IPsec, OpenVPN, WireGuard, L2TP, PPTP -- [NAT]({{ baseurl }}configuration/nat/index.html): Source NAT, destination NAT, NAT66 -- [System]({{ baseurl }}configuration/system/index.html): DNS, NTP, syslog, users, task scheduler -- [High Availability]({{ baseurl }}configuration/highavailability/index.html): VRRP -- [Load Balancing]({{ baseurl }}configuration/loadbalancing/index.html): WAN and reverse proxy -- [Containers]({{ baseurl }}configuration/container/index.html): Podman-based container support -- [PKI]({{ baseurl }}configuration/pki/index.html): Certificate management -- [Policy]({{ baseurl }}configuration/policy/index.html): Route maps, prefix lists, access lists -- [Traffic Policy]({{ baseurl }}configuration/trafficpolicy/index.html): QoS and shaping -- [Service]({{ baseurl }}configuration/service/index.html): DHCP, DNS forwarding, SNMP, SSH, HTTPS API -- [VRF]({{ baseurl }}configuration/vrf/index.html): Virtual routing and forwarding +- [Firewall]({{ baseurl }}configuration/firewall/index.md): Zone-based firewall, rules, groups +- [Interfaces]({{ baseurl }}configuration/interfaces/index.md): Ethernet, bonding, bridge, VLAN, tunnel, wireless +- [Protocols]({{ baseurl }}configuration/protocols/index.md): BGP, OSPF, IS-IS, static routing, MPLS +- [VPN]({{ baseurl }}configuration/vpn/index.md): IPsec, OpenVPN, WireGuard, L2TP, PPTP +- [NAT]({{ baseurl }}configuration/nat/index.md): Source NAT, destination NAT, NAT66 +- [System]({{ baseurl }}configuration/system/index.md): DNS, NTP, syslog, users, task scheduler +- [High Availability]({{ baseurl }}configuration/highavailability/index.md): VRRP +- [Load Balancing]({{ baseurl }}configuration/loadbalancing/index.md): WAN and reverse proxy +- [Containers]({{ baseurl }}configuration/container/index.md): Podman-based container support +- [PKI]({{ baseurl }}configuration/pki/index.md): Certificate management +- [Policy]({{ baseurl }}configuration/policy/index.md): Route maps, prefix lists, access lists +- [Traffic Policy]({{ baseurl }}configuration/trafficpolicy/index.md): QoS and shaping +- [Service]({{ baseurl }}configuration/service/index.md): DHCP, DNS forwarding, SNMP, SSH, HTTPS API +- [VRF]({{ baseurl }}configuration/vrf/index.md): Virtual routing and forwarding ## Operations -- [Operational Commands]({{ baseurl }}operation/index.html): Show, monitor, restart commands +- [Operational Commands]({{ baseurl }}operation/index.md): Show, monitor, restart commands ## Installation -- [Installation Guide]({{ baseurl }}installation/index.html): Bare metal, virtual, cloud deployments +- [Installation Guide]({{ baseurl }}installation/index.md): Bare metal, virtual, cloud deployments ## Automation -- [Automation]({{ baseurl }}automation/index.html): Ansible, Terraform, HTTP API, NETCONF +- [Automation]({{ baseurl }}automation/index.md): Ansible, Terraform, HTTP API, NETCONF ## Configuration Examples -- [Blueprints]({{ baseurl }}configexamples/index.html): Real-world topology examples +- [Blueprints]({{ baseurl }}configexamples/index.md): Real-world topology examples ## Optional -- [Contributing]({{ baseurl }}contributing/index.html): Development workflow -- [VPP]({{ baseurl }}vpp/index.html): Vector Packet Processing integration +- [Contributing]({{ baseurl }}contributing/index.md): Development workflow +- [VPP]({{ baseurl }}vpp/index.md): Vector Packet Processing integration -- cgit v1.2.3 From 7bdb29a042faaa9e4f125c8c479fe35f54d8a2e6 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Thu, 7 May 2026 09:40:51 +0300 Subject: docs(llms.txt): update dirhtml-skip rationale after .md pivot MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous comment on `_write_llms_txt` (and on the LLM-Facing Files section in CLAUDE.md) justified the `dirhtml` skip by claiming the template's `.html` URLs wouldn't resolve under `dirhtml` output. That became stale after [#1874@5fe7f9ad](https://github.com/vyos/vyos-documentation/pull/1874/commits/5fe7f9ad) (and parity commits on [#1876](https://github.com/vyos/vyos-documentation/pull/1876)/[#1903](https://github.com/vyos/vyos-documentation/pull/1903)) pivoted the curated template to `.md` URLs — `_copy_md_sources` puts `.md` files at their source-relative paths regardless of builder, so the rendered llms.txt would actually resolve fine under `dirhtml` now. The real reason we skip `dirhtml` is simpler: production publishes only via the `html`/`readthedocs` builders, and we don't render llms.txt for builds we don't ship. Local `make dirhtml` is a developer convenience, not a publish target. Reword the conf.py comment and the CLAUDE.md section to say that plainly. No code-behavior change. Addresses Copilot review feedback on PR #1874 (3 threads on docs/conf.py, docs/_templates/llms.txt.j2, and CLAUDE.md flagging the inconsistency). \xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io) --- docs/conf.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 26ce346c..dddb78fe 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -267,10 +267,12 @@ def _write_llms_txt(app, exception): ``release``, and writes ``/llms.txt``. ``llms-full.txt`` is handled separately by the ``sphinx_llms_txt`` extension. """ - # Skip dirhtml: the curated template encodes `.html` URLs (e.g. - # `quick-start.html`), which don't exist under `dirhtml` output - # (`quick-start/index.html`). Production publishes via the html / - # readthedocs builders, so dirhtml output would just be misleading. + # Skip dirhtml: production publishes via the `html` / `readthedocs` + # builders only. The `.md` links in the curated template do + # actually resolve under `dirhtml` (`_copy_md_sources` puts `.md` + # files at their source-relative paths regardless of builder), but + # we still don't render llms.txt for builds we don't ship — local + # `make dirhtml` is a developer convenience, not a publish target. if exception is not None or app.builder.name not in ( 'html', 'readthedocs'): return -- cgit v1.2.3 From 310cf6a0b7f532fd7f2de7c8a6c2006838b7f838 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Thu, 7 May 2026 09:48:10 +0300 Subject: docs(conf.py): fix stale .html reference in fail-fast comment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Last residual `.html` reference in the `_write_llms_txt` hook comments — the html_baseurl-empty failure-path comment said "rendering /quick-start.html etc." but the template now emits `.md` URLs. Update the example to `/quick-start.md` to match the actual output. Comment-only change. Same fix applied symmetrically across [#1874](https://github.com/vyos/vyos-documentation/pull/1874), [#1876](https://github.com/vyos/vyos-documentation/pull/1876), and [#1903](https://github.com/vyos/vyos-documentation/pull/1903). Addresses Copilot review feedback on PR #1903. \xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io) --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index dddb78fe..5ede415e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -277,7 +277,7 @@ def _write_llms_txt(app, exception): 'html', 'readthedocs'): return if not app.config.html_baseurl: - # Fail loudly rather than rendering /quick-start.html etc. as a + # Fail loudly rather than rendering /quick-start.md etc. as a # silently-broken root-relative URL — every supported branch # sets html_baseurl, so a missing value is a regression. raise RuntimeError( -- cgit v1.2.3