Metadata-Version: 2.5
Name: sphinx-llm-friendly
Version: 0.4.0
Summary: Sphinx extension to make documentation LLM-friendly
Project-URL: Source, https://github.com/scrapy/sphinx-llm-friendly
Project-URL: Tracker, https://github.com/scrapy/sphinx-llm-friendly/issues
Project-URL: Release notes, https://github.com/scrapy/sphinx-llm-friendly/blob/main/CHANGES.rst
Author-email: Scrapy developers <opensource@zyte.com>
Maintainer-email: Scrapy developers <opensource@zyte.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Documentation :: Sphinx
Requires-Python: >=3.10
Requires-Dist: docutils
Requires-Dist: sphinx>=7.4
Requires-Dist: tabulate
Description-Content-Type: text/x-rst

===================
sphinx-llm-friendly
===================

`Sphinx <https://www.sphinx-doc.org/>`_ extension that makes documentation
LLM-friendly:

-   A Markdown version of every page, next to its HTML version.

-   `llms.txt <https://llmstxt.org/>`_, with a link to the Markdown version of
    every page.

-   ``llms-full.txt``, with the Markdown version of all pages.

-   HTML pages point to their Markdown version with a ``<link
    rel="alternate" type="text/markdown">`` tag, and get a button to copy
    their Markdown version.

Setup
=====

#.  Install it:

    .. code-block:: shell

        pip install sphinx-llm-friendly

#.  Add it to ``extensions`` in ``conf.py``:

    .. code-block:: python

        extensions = [
            # …
            "sphinx_llm_friendly",
        ]

#.  Build your documentation with the ``html`` builder:

    .. code-block:: shell

        sphinx-build -b html docs docs/_build/html

    The Markdown pages, ``llms.txt`` and ``llms-full.txt`` are written next to
    the HTML pages. In the Markdown output, links to sites from
    ``intersphinx_mapping`` that serve Markdown point to the Markdown version
    of their pages.

Configuration
=============

``llm_friendly_exclude``
    List of patterns, with the syntax of ``exclude_patterns``, of documents to
    leave out of the Markdown output and ``llms.txt``. Default: ``[]``.

``llm_friendly_llms_full_txt_exclude``
    List of patterns, with the syntax of ``exclude_patterns``, of documents to
    leave out of ``llms-full.txt`` only. Default: ``[]``.

``llm_friendly_llms_txt_summary``
    Summary for ``llms.txt``. Default: the first paragraph of the root
    document.

``llm_friendly_llms_txt_toctree_only``
    If ``True``, ``llms.txt`` only lists documents reachable through toctrees
    from the root document. Default: ``False``.

To leave content out of the Markdown output, give it the
``llm-friendly-exclude`` class, e.g. with the ``container`` directive.

For the Markdown output, the ``only`` directive evaluates its expression with
the ``llm`` tag instead of ``html``, e.g. use ``.. only:: llm`` for content to
include only in the Markdown output, and ``.. only:: not llm`` for content to
leave out of it.

Nodes from third-party extensions that are still in the doctree when HTML is
written need Markdown handlers, registered with ``app.add_node()`` as
``llm_markdown``.
