From ab5bcd24bb8c3e311e31c09980c8defefb3c8e74 Mon Sep 17 00:00:00 2001
From: Yuriy Andamasov <yuriy@vyos.io>
Date: Mon, 4 May 2026 11:07:46 +0300
Subject: docs: add llms.txt and llms-full.txt generation (sagitta)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Pin sphinx-llms-txt 0.7.1 and sphinx-sitemap 2.9.0
- Set html_baseurl to https://docs.vyos.io/en/sagitta/
- llms.txt rendered at build time from a Jinja template; llms-full.txt
  auto-generated by sphinx-llms-txt
- Optional section adapted to sagitta layout (no contributing index, no VPP)
- Same change applied to current and circinus in separate PRs

🤖 Generated by [robots](https://vyos.io)
---
 docs/_templates/llms.txt.j2 | 53 +++++++++++++++++++++++++++++++++++++++++++++
 docs/conf.py                | 30 +++++++++++++++++++++++--
 2 files changed, 81 insertions(+), 2 deletions(-)
 create mode 100644 docs/_templates/llms.txt.j2

(limited to 'docs')

diff --git a/docs/_templates/llms.txt.j2 b/docs/_templates/llms.txt.j2
new file mode 100644
index 00000000..e1e466a0
--- /dev/null
+++ b/docs/_templates/llms.txt.j2
@@ -0,0 +1,53 @@
+# 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
+
+- [Build VyOS]({{ baseurl }}contributing/build-vyos.html): Building images from source
+- [Development]({{ baseurl }}contributing/development.html): Development workflow
+- [Debugging]({{ baseurl }}contributing/debugging.html): Debugging VyOS
diff --git a/docs/conf.py b/docs/conf.py
index 7d933306..9bfdd4d9 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -48,7 +48,9 @@ extensions = ['sphinx.ext.intersphinx',
               'autosectionlabel',
               'myst_parser',
               'sphinx_design',
-              'vyos'
+              'vyos',
+              'sphinx_llms_txt',
+              'sphinx_sitemap',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -98,6 +100,15 @@ todo_include_todos = True
 #
 html_theme = "sphinx_rtd_theme"
 
+html_baseurl = 'https://docs.vyos.io/en/sagitta/'
+
+# sphinx-sitemap: baseurl already includes /en/sagitta/, so skip lang+version
+sitemap_url_scheme = '{link}'
+
+# sphinx-llms-txt: disable auto-generated llms.txt, keep curated render via setup
+# hook; llms-full.txt is still auto-generated
+llms_txt_file = False
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
@@ -193,5 +204,20 @@ texinfo_documents = [
 ]
 
 
+def _write_llms_txt(app, exception):
+    if exception is not None or app.builder.name != 'html':
+        return
+    from pathlib import Path
+    from jinja2 import Template
+    tpl_path = Path(app.srcdir) / '_templates' / 'llms.txt.j2'
+    out_path = Path(app.outdir) / 'llms.txt'
+    baseurl = (app.config.html_baseurl or '').rstrip('/') + '/'
+    rendered = Template(tpl_path.read_text(encoding='utf-8')).render(
+        baseurl=baseurl,
+        release=app.config.release,
+    )
+    out_path.write_text(rendered, encoding='utf-8')
+
+
 def setup(app):
-    pass
+    app.connect('build-finished', _write_llms_txt)
-- 
cgit v1.2.3