---
myst:
    html_meta:
        "description": "Make ROCm documentation accessible to AI agents and coding assistants using a curated index and a generated full-text file, plus the per-page download button"
        "keywords": "LLM documentation, AI agent, download button, ROCm docs core user guide"
---

# LLM-friendly output

`rocm-docs-core` supports three features that make documentation more accessible to AI coding assistants and agents:

- A per-page **download button** that lets users and agents copy page content directly into an AI context window.
- A curated **`llms.txt`** index file that AI agents can discover and use as an entry point to the documentation.
- A generated **`llms-full.txt`** file that aggregates prose content from all source files into a single plain-text document.

All three features are opt-in and configured in `conf.py`.

## Per-page download button

The Sphinx Book Theme includes a built-in download button that lets readers download the current page as Markdown or RST. Enable it by setting `use_download_button` in `html_theme_options`:

```python
html_theme_options = {
    "use_download_button": True,
}
```

Once enabled, a download icon appears on each page. Clicking it downloads the source file for that page, which users and agents can paste directly into an AI context window.

## `llms.txt`

`llms.txt` is a curated index of your documentation pages, following the [llmstxt.org](https://llmstxt.org/) convention for AI agent documentation discovery. It is also compatible with [Read the Docs llms-txt support](https://docs.readthedocs.com/platform/stable/reference/llms-txt.html).

### Creating the index file

Create a `llms.txt` file in your documentation source directory (the same directory as `conf.py`). Write it as a Markdown document with a project description followed by links to your key pages:

```markdown
# Project name

> One-sentence description of the project.

## User guide

- [Page title](https://your-docs-url/page-slug): Short description of the page.
- [Another page](https://your-docs-url/another-page): Short description.
```

### Publishing the index file

Add `llms.txt` to `html_extra_path` in `conf.py` so Sphinx copies it to the output root:

```python
html_extra_path = ["llms.txt"]
```

After a successful build, `llms.txt` is available at `{project_url}/llms.txt`.

### Header behavior in the full-text file

If `llms.txt` is present in the source directory, it is also used as the header section of `llms-full.txt`. If no `llms.txt` is present, the Sphinx `project` name from `conf.py` is used as the header instead.

## `llms-full.txt`

`llms-full.txt` is generated by `rocm-docs-core` after each successful build. It aggregates prose content from all `.md` and `.rst` source files into a single plain-text document.

### Enabling generation

Set `rocm_docs_generate_llms_full = True` in `conf.py`:

```python
rocm_docs_generate_llms_full = True
```

The file is not generated if the build fails.

### Output location

`llms-full.txt` is written to the Sphinx output directory alongside the built HTML. For a standard build this is `docs/_build/html/llms-full.txt`, making it available at `{project_url}/llms-full.txt`.

### Content filtering

The generator filters source files to keep only meaningful prose:

- Files with fewer than 10 prose lines are skipped entirely, excluding navigation-only or boilerplate pages.
- Files in `_build`, `_static`, `_templates`, `.git`, and `.venv` directories are excluded.
- Markup noise is stripped from included files: directive syntax, anchor labels, table separator rows, raw HTML blocks, and RST section underlines.
- Code blocks are preserved.

Each included file is appended as a section separated by `---`, with its path relative to the source directory used as the section heading.

## Example configuration

The following example enables all three features together:

```python
html_theme_options = {
    "use_download_button": True,
}

html_extra_path = ["llms.txt"]

rocm_docs_generate_llms_full = True
```
