[docs] Demo all format options (#60)

.readthedocs.yml

@@ -9,6 +9,8 @@ build:
     - pip install -r docs/requirements.txt
     - pip install -e .
     - cmake --workflow --preset documentation-workflow
+    # Generate llms.txt variants for demo purposes
+    - python docs/generate_llms_variants.py build/html
     # Copy built documentation to Read the Docs output directory
     - mkdir -p $READTHEDOCS_OUTPUT/html
     - cp -r build/html/* $READTHEDOCS_OUTPUT/html/

docs/generate_llms_variants.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""
+Generate variant llms.txt files for demo purposes.
+
+Takes the generated llms.txt (with _sources links) and creates:
+- llms.txt - default with _sources links (unchanged)
+- llms.md.txt - .html.md links
+- llms.rst.txt - .rst links
+"""
+
+import re
+import sys
+from pathlib import Path
+
+
+def get_base_url() -> str:
+    """Import base_url from conf.py."""
+    sys.path.insert(0, str(Path(__file__).parent / "source"))
+    from conf import html_baseurl  # noqa: E402
+
+    return html_baseurl
+
+
+def generate_variants(build_dir: Path) -> None:
+    """Generate llms.txt variants from the original file."""
+    original = build_dir / "llms.txt"
+
+    if not original.exists():
+        print(f"Error: {original} not found")
+        sys.exit(1)
+
+    content = original.read_text()
+    base_url = get_base_url()
+
+    # Pattern to match links like: https://.../_sources/{docname}.rst.txt
+    link_pattern = re.compile(
+        rf"({re.escape(base_url)})_sources/([a-zA-Z0-9_/\-]+)\.rst\.txt"
+    )
+
+    # Generate .html.md variant
+    md_content = link_pattern.sub(r"\1\2.html.md", content)
+    (build_dir / "llms.md.txt").write_text(md_content)
+    print(f"Generated: {build_dir / 'llms.md.txt'} (.html.md links)")
+
+    # Generate .rst variant
+    rst_content = link_pattern.sub(r"\1\2.rst", content)
+    (build_dir / "llms.rst.txt").write_text(rst_content)
+    print(f"Generated: {build_dir / 'llms.rst.txt'} (.rst links)")
+
+    print(f"Kept: {build_dir / 'llms.txt'} (_sources links)")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1:
+        build_dir = Path(sys.argv[1])
+    else:
+        build_dir = Path("build/html")
+
+    generate_variants(build_dir)

docs/source/conf.py

@@ -16,7 +16,6 @@ project = "sphinx-llms-txt"
 copyright = "Jared Dillard"
 author = "Jared Dillard"
 
-llms_txt_uri_template = "{base_url}{docname}.html.md"
 llms_txt_code_files = ["+:../../sphinx_llms_txt/*.py"]
 llms_txt_summary = """
 A Sphinx extension that generates a summary llms.txt file,written in Markdown,

docs/source/getting-started.rst

@@ -34,6 +34,8 @@ After the HTML finishes building, **sphinx-llms-txt** will output the location o
     sphinx-llms-txt: Created /path/to/_build/html/llms-full.txt with 45 sources and 6879 lines
     sphinx-llms-txt: created /path/to/_build/html/llms.txt
 
+.. _choosing-output-format:
+
 Choosing an Output Format
 -------------------------
 
@@ -45,17 +47,21 @@ For optimal LLM support, see the alternative builders below and the :ref:`CMake
    :widths: 18 27 27 27
 
    * -
-     - Default (no config)
+     - Default
-     - Markdown (CMake)
+     - Markdown
-     - RST (CMake)
+     - reStructuredText
+   * - **Setup**
+     - No config
+     - CMake
+     - CMake
    * - **Builder**
      - Native [#native]_
      - `sphinx-markdown-builder`_
      - `sphinxcontrib-restbuilder`_
    * - **Format**
-     - Raw RST source
+     - Raw reStructuredText source
      - Rendered Markdown [#rendered]_
-     - Rendered RST [#rendered]_
+     - Rendered reStructuredText [#rendered]_
    * - **LLM Readability**
      - Good - preserves structure for simple syntax
      - Excellent - native LLM format

docs/source/index.rst

@@ -8,7 +8,9 @@ A `Sphinx`_ extension that generates a summary ``llms.txt`` file, written in Mar
 Demo
 ----
 
-You can see this Sphinx project's `llms.txt`_ and `llms-full.txt`_ files as a simple example.
+This Sphinx project's `llms.txt`_ and `llms-full.txt`_ files as an example of the default output format.
+
+Alternative :ref:`output formats <choosing-output-format>` are also available. For example: `Markdown`_ and `reStructuredText`_.
 
 Highlights
 ----------
@@ -36,6 +38,8 @@ Highlights
 
 .. _llms.txt: https://sphinx-llms-txt.readthedocs.io/en/latest/llms.txt
 .. _llms-full.txt: https://sphinx-llms-txt.readthedocs.io/en/latest/llms-full.txt
+.. _Markdown: https://sphinx-llms-txt.readthedocs.io/en/latest/llms.md.txt
+.. _reStructuredText: https://sphinx-llms-txt.readthedocs.io/en/latest/llms.rst.txt
 .. _Sphinx: http://sphinx-doc.org/
 
 .. |PyPI version| image:: https://img.shields.io/pypi/v/sphinx-llms-txt.svg