79 lines
2.3 KiB
ReStructuredText
79 lines
2.3 KiB
ReStructuredText
Getting Started
|
|
===============
|
|
|
|
Installation
|
|
------------
|
|
|
|
Directly install by using:
|
|
|
|
.. tab:: via pip
|
|
|
|
.. code-block:: bash
|
|
|
|
pip install sphinx-llms-txt
|
|
|
|
.. tab:: via conda:
|
|
|
|
.. code-block:: bash
|
|
|
|
conda install -c conda-forge sphinx-llms-txt
|
|
|
|
Usage
|
|
-----
|
|
|
|
Add the extension to your Sphinx configuration (``conf.py``):
|
|
|
|
.. code-block:: python
|
|
|
|
extensions = [
|
|
'sphinx_llms_txt',
|
|
]
|
|
|
|
After the HTML finishes building, **sphinx-llms-txt** will output the location of the output files::
|
|
|
|
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 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>`.
|
|
|
|
.. list-table:: Output Format Comparison
|
|
:header-rows: 1
|
|
:widths: 18 27 27 27
|
|
|
|
* -
|
|
- Default (no config)
|
|
- Markdown (CMake)
|
|
- RST (CMake)
|
|
* - **Format**
|
|
- Raw RST source
|
|
- Rendered Markdown
|
|
- Rendered RST
|
|
* - **LLM Readability**
|
|
- Good - preserves structure for simple syntax
|
|
- Excellent - native LLM format
|
|
- Good - Can provide more structured content
|
|
* - **Key Advantage**
|
|
- Zero setup required
|
|
- More compact (less input tokens)
|
|
- Can preserve Sphinx semantics
|
|
* - **Key Disadvantage**
|
|
- Raw directives (e.g., autodoc) won't be parsed
|
|
- 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.
|
|
|
|
.. _sphinx-markdown-builder: https://pypi.org/project/sphinx-markdown-builder/
|
|
.. _sphinxcontrib-restbuilder: https://pypi.org/project/sphinxcontrib-restbuilder/
|
|
|