Merge pull request #1874 from vyos/feat/docs-llms-txt-current

docs: render llms.txt at build time (current)

1 files changed, 61 insertions, 8 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 76a00577..da462b0e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -26,11 +26,16 @@ project = u'VyOS'
 copyright = u'2026, VyOS maintainers and contributors'
 author = u'VyOS maintainers and contributors'
 
-# The short X.Y version
-version = u'1.5'
+# The short X.Y version (rolling — next major; bumped at branch cut)
+version = u'rolling'
 
-# The full version, including alpha/beta/rc tags
-release = u'1.5.x (circinus)'
+# The full version, including alpha/beta/rc tags. The `current` branch
+# is the rolling tip and serves at /en/rolling/ on RTD; the literal
+# below is exposed in the page footer ("v: rolling (current)") and is
+# interpolated into _templates/llms.txt.j2 ("This documentation covers
+# {{ release }}."). Pin this to a value that names what the rolling
+# docs actually serve, not a stale LTS codename.
+release = u'rolling (current)'
 
 # -- General configuration ---------------------------------------------------
 
@@ -127,7 +132,7 @@ html_static_path = ['_static']
 
 html_extra_path = ['_html_extra']
 
-html_baseurl = 'https://docs.vyos.io/en/latest/'
+html_baseurl = 'https://docs.vyos.io/en/rolling/'
 
 _rtd_version_type = os.environ.get('READTHEDOCS_VERSION_TYPE', '')
 _github_version = (
@@ -144,11 +149,13 @@ html_context = {
     'conf_py_path': '/docs/',
 }
 
-# sphinx-sitemap: baseurl already includes /en/latest/, so skip lang+version
+# sphinx-sitemap: baseurl already includes /en/rolling/, 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
@@ -246,6 +253,51 @@ def _prefer_webp(app):
             app.builder.supported_image_types = ['image/webp'] + types
 
 
+def _write_llms_txt(app, exception):
+    # 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
+    if not app.config.html_baseurl:
+        # 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(
+            'html_baseurl must be set to render llms.txt')
+    from pathlib import Path
+    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('/') + '/'
+    # 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,
+        # 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(
+        baseurl=baseurl,
+        release=app.config.release,
+    )
+    out_path.write_text(rendered, encoding='utf-8')
+
+
 def _copy_md_sources(app, exception):
     """Copy .md source files verbatim into the HTML output tree."""
     if exception is not None:
@@ -261,3 +313,4 @@ def _copy_md_sources(app, exception):
 def setup(app):
     app.connect('builder-inited', _prefer_webp)
     app.connect('build-finished', _copy_md_sources)
+    app.connect('build-finished', _write_llms_txt)