Metadata-Version: 2.4
Name: sphinx-llms-txt-link
Version: 0.1
Summary: Sphinx extension for llms.txt links.
Author-email: Artur Barseghyan <artur.barseghyan@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/barseghyanartur/sphinx-llms-txt-link/
Project-URL: Bug Tracker, https://github.com/barseghyanartur/sphinx-llms-txt-link/issues
Project-URL: Documentation, https://sphinx-llms-txt-link.readthedocs.io/
Project-URL: Source Code, https://github.com/barseghyanartur/sphinx-llms-txt-link/
Project-URL: Changelog, https://sphinx-llms-txt-link.readthedocs.io/en/latest/changelog.html
Keywords: sphinx,documentation,pragma
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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.9
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: docutils
Requires-Dist: sphinx
Provides-Extra: all
Requires-Dist: sphinx-llms-txt-link[dev,docs,test]; extra == "all"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: detect-secrets; extra == "dev"
Requires-Dist: doc8; extra == "dev"
Requires-Dist: ipython; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pkginfo; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: uv; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-codeblock; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
Requires-Dist: sphinx-no-pragma; extra == "docs"
Dynamic: license-file

====================
sphinx-llms-txt-link
====================
.. External references

.. _Sphinx: https://github.com/sphinx-doc/sphinx
.. _Read the Docs: http://readthedocs.org/
.. _LLMOps: https://en.wikipedia.org/wiki/LLMOps
.. _AI Safety: https://en.wikipedia.org/wiki/AI_safety

.. Internal references

.. _sphinx-llms-txt-link: https://github.com/barseghyanartur/sphinx-llms-txt-link/
.. _Read the Docs project: http://sphinx-llms-txt-link.readthedocs.io/
.. _Contributor guidelines: https://sphinx-llms-txt-link.readthedocs.io/en/latest/contributor_guidelines.html
.. _llms.txt: https://barseghyanartur.github.io/sphinx-llms-txt-link/llms.txt

Automatically add a static link to the raw rendered text
version (reStructuredText or Markdown format) of every HTML
documentation page.

**Optimize for LLM Consumption**:

- Provides a direct link to the **raw, rendered text markup** for the current
  page.
- Enables developers to quickly copy clean, structured context for feeding
  into an LLM prompt.

.. image:: https://img.shields.io/pypi/v/sphinx-llms-txt-link.svg
   :target: https://pypi.python.org/pypi/sphinx-llms-txt-link.py
   :alt: PyPI Version

.. image:: https://img.shields.io/pypi/pyversions/sphinx-llms-txt-link.svg
    :target: https://pypi.python.org/pypi/sphinx-llms-txt-link/
    :alt: Supported Python versions

.. image:: https://github.com/barseghyanartur/sphinx-llms-txt-link/actions/workflows/test.yml/badge.svg?branch=main
   :target: https://github.com/barseghyanartur/sphinx-llms-txt-link/actions
   :alt: Build Status

.. image:: https://readthedocs.org/projects/sphinx-llms-txt-link/badge/?version=latest
    :target: http://sphinx-llms-txt-link.readthedocs.io
    :alt: Documentation Status

.. image:: https://img.shields.io/badge/docs-llms.txt-blue
    :target: https://barseghyanartur.github.io/sphinx-llms-txt-link/llms.txt
    :alt: llms.txt - documentation for LLMs

.. image:: https://img.shields.io/badge/license-MIT-blue.svg
   :target: https://github.com/barseghyanartur/sphinx-llms-txt-link/#License
   :alt: MIT

.. image:: https://coveralls.io/repos/github/barseghyanartur/sphinx-llms-txt-link/badge.svg?branch=main&service=github
    :target: https://coveralls.io/github/barseghyanartur/sphinx-llms-txt-link?branch=main
    :alt: Coverage

**TL;DR**

`sphinx-llms-txt-link`_ is a `Sphinx`_ extension that injects
a **server-side rendered** link to the `.txt` version of each HTML page,
specifically optimized for `LLMOps`_ and training consumption.

Features
========
- **Server-Side Injection:** Uses the `doctree-resolved` hook to insert
  a `docutils.nodes.raw` element, ensuring the link is in the static HTML
  source.
- **100% Indexable:** Guarantees visibility for all crawlers (Google,
  specialized LLM scrapers, RAG indexers).
- **Theme Agnostic:** Works reliably across themes (Read the Docs, Alabaster,
  Furo, etc.) without requiring template overrides.
- **Auto-Calculated Relative Path:** Correctly calculates the relative path
  to the sibling `.txt` file, avoiding common issues with Sphinx's internal
  link resolution.
- **Simple Styling Integration:** Injects a standard CSS
  class (`sphinx-llms-txt-link`) for easy styling and theme-specific
  overrides.

Prerequisites
=============
- Python 3.10+
- Sphinx 6.0+

Your Sphinx documentation must be configured to output `.txt` files (e.g.,
using `sphinx_markdown_builder` or ensuring the `text` builder runs).

Installation
============
.. code-block:: sh

    pip install sphinx-llms-txt-link

Documentation
=============
- Documentation is available on the `Read the Docs project`_.
- For guidelines on contributing check the `Contributor guidelines`_.

Usage example
=============
Sphinx configuration
--------------------

Essential configuration
~~~~~~~~~~~~~~~~~~~~~~~
Add the extension to your `conf.py`. No other configuration is required.

*Filename: docs/conf.py*

.. code-block:: python
    :name: test_docs_conf_extensions

    extensions = [
        # ... other extensions
        "sphinx_llms_txt_link",
        # ... other extensions
    ]

Custom styling (optional)
~~~~~~~~~~~~~~~~~~~~~~~~~

The extension injects the following minimal HTML structure at the end of the
document body:

.. code-block:: html

    <div class="llm-link-container">
        <a href="current_page_name.txt" class="llm-link">
            View llms.txt version
        </a>
    </div>

If you wish to style the link to match your theme (e.g., `Alabaster` or
`Read the Docs`), you can create a CSS file (e.g.,
`_static/custom_sphinx_llms_txt_link.css`) and include it in
your `conf.py` settings:

*Filename: docs/conf.py*

.. code-block:: python
    :name: test_docs_conf_add_css

    html_css_files = [
        "custom_sphinx_llms_txt_link.css",
    ]

Build process
~~~~~~~~~~~~~
Ensure you run the standard HTML build command. If you use a tool
like `sphinx-markdown-builder` or a custom extension to generate the `.txt`
artifacts, ensure those artifacts exist in the build directory.

.. code-block:: sh

    # Build the .txt files
    sphinx-build -n -b text docs builddocs

    # Build the HTML output and inject the link
    sphinx-build -n -a -b html docs builddocs

The link will now appear at the bottom of every generated HTML page, pointing
correctly to its `.txt` counterpart.

Tests
=====
Run the tests with pytest:

.. code-block:: sh

    pytest

License
=======
MIT

Support
=======
For security issues contact me at the e-mail given in the `Author`_ section.

For overall issues, go to
`GitHub <https://github.com/barseghyanartur/sphinx-llms-txt-link/issues>`_.

Author
======
Artur Barseghyan <artur.barseghyan@gmail.com>
