[docs] Improve docs wording (#59)

This commit is contained in:
Jared Dillard
2025-12-07 23:26:27 -08:00
committed by GitHub
parent 5b1b72bafb
commit 8254002622
2 changed files with 22 additions and 13 deletions
+19 -12
View File
@@ -37,8 +37,8 @@ After the HTML finishes building, **sphinx-llms-txt** will output the location o
Choosing an Output Format
-------------------------
By default, **sphinx-llms-txt** requires no additional configuration and links to raw reStructuredText source files in :confval:`_sources/ <sphinx:html_copy_source>`.
For optimal LLM support, you can use `sphinx-markdown-builder`_ and/or `sphinxcontrib-restbuilder`_, set up in parallel builds using :ref:`CMake <cmake_workflow>`.
By default, **sphinx-llms-txt** requires no additional configuration and links to raw reStructuredText source files created by the HTML builder.
For optimal LLM support, see the alternative builders below and the :ref:`CMake workflow <cmake_workflow>` for setup.
.. list-table:: Output Format Comparison
:header-rows: 1
@@ -48,10 +48,14 @@ For optimal LLM support, you can use `sphinx-markdown-builder`_ and/or `sphinxco
- Default (no config)
- Markdown (CMake)
- RST (CMake)
* - **Builder**
- Native [#native]_
- `sphinx-markdown-builder`_
- `sphinxcontrib-restbuilder`_
* - **Format**
- Raw RST source
- Rendered Markdown
- Rendered RST
- Rendered Markdown [#rendered]_
- Rendered RST [#rendered]_
* - **LLM Readability**
- Good - preserves structure for simple syntax
- Excellent - native LLM format
@@ -61,18 +65,21 @@ For optimal LLM support, you can use `sphinx-markdown-builder`_ and/or `sphinxco
- More compact (less input tokens)
- Can preserve Sphinx semantics
* - **Key Disadvantage**
- Raw directives (e.g., autodoc) won't be parsed
- Raw directives won't be parsed [#autodoc]_
- Loses structure from complex directives
- Can lose structure from complex directives
* - **llms-full.txt support**
- Suported with above caveats
- Pending `support <https://github.com/liran-funaro/sphinx-markdown-builder/pull/37>`__
- Pending `support <https://github.com/sphinx-contrib/restbuilder/pull/35>`__
See :ref:`cmake_workflow` for an example of building HTML, Markdown, and RST in parallel.
Use :confval:`llms_txt_uri_template` to configure links to point to your preferred format.
- Supported with above caveats
- Pending `support <https://github.com/liran-funaro/sphinx-markdown-builder/pull/37>`__ [#pending]_
- Pending `support <https://github.com/sphinx-contrib/restbuilder/pull/35>`__ [#pending]_
.. _sphinx-markdown-builder: https://pypi.org/project/sphinx-markdown-builder/
.. _sphinxcontrib-restbuilder: https://pypi.org/project/sphinxcontrib-restbuilder/
.. rubric:: Footnotes
.. [#native] Uses raw :confval:`_sources/ <sphinx:html_copy_source>` files created by Sphinx's HTML builder with some minor enhancements.
.. [#autodoc] Directives like ``autodoc`` will appear as raw directive syntax rather than the extracted docstrings.
.. [#pending] PRs that add ``llms-full.txt`` concatenation support have yet to be released.
.. [#rendered] Directives are expanded and processed before output, so content like autodoc docstrings will be included.