From 1ce4a62f07759fc4bedd127236ef64110a1e8f89 Mon Sep 17 00:00:00 2001
From: Yuriy Andamasov <yuriy@vyos.io>
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