diff --git a/.readthedocs.yml b/.readthedocs.yml index 6731102..4b5ae68 100644 --- a/.readthedocs.yml +++ b/.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/ diff --git a/docs/generate_llms_variants.py b/docs/generate_llms_variants.py new file mode 100644 index 0000000..352c2f0 --- /dev/null +++ b/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) diff --git a/docs/source/conf.py b/docs/source/conf.py index 0ca7a1a..5a4185f 100644 --- a/docs/source/conf.py +++ b/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, diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index 95b31f4..4bb258d 100644 --- a/docs/source/getting-started.rst +++ b/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) - - Markdown (CMake) - - RST (CMake) + - Default + - Markdown + - 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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 7bc483d..8032307 100644 --- a/docs/source/index.rst +++ b/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 ` 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