> For the complete documentation index, see [llms.txt](https://docs.vale.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vale.sh/formats/sphinx.md).

# Sphinx

Learn how Vale handles a Sphinx project.

{% hint style="info" %}
Requires Vale v3.23.0 or later.
{% endhint %}

A [Sphinx](https://www.sphinx-doc.org/) project is reStructuredText, or MyST, plus the directives and roles Sphinx and its extensions define: `versionadded`, `seealso`, `toctree`, `:ref:`, `:func:`, and whatever `sphinx-tabs`, `sphinx-design`, or the project's own `conf.py` adds. Vale reads it through [Docutils](/formats/restructuredtext.md), the way it reads any reStructuredText, and does not need Sphinx installed.

## [Directives and roles](#directives-and-roles)

Docutils knows only its own directives and roles, so Vale decides the rest by a rule that fits nearly every Sphinx construct: the body of a directive Docutils doesn't define is prose, and the text of a role it doesn't define is code. A `versionadded`, a `seealso`, a `tab`, a `grid` card, or a `py:function` description is linted like any paragraph; `:func:`, `:class:`, and `:doc:` are left alone.

The exceptions Vale knows are Sphinx's own. `toctree`, `literalinclude`, `math`, the `auto*` family, and the doctest blocks are not prose. `ref`, `doc`, `any`, `numref`, `term`, `guilabel`, `menuselection`, `abbr`, and `dfn` carry prose: a reference written with a title, `` :ref:`the setup guide <setup>` `` , is linted as its title, and a bare target such as `` :doc:`guide/setup` `` is code.

An extension's additions that don't fit the rule are named in a `[sphinx]` section. Both keys add to the built-in lists:

```ini
StylesPath = styles

[sphinx]
# Directives whose body is code, data, or a diagram: not linted.
CodeDirectives = mermaid, plantuml
# Roles whose text is prose rather than an identifier.
ProseRoles = kbd, samp

[*.rst]
BasedOnStyles = Vale
```

## [What is and isn't read](#what-is-and-isnt-read)

Vale lints the source as written. Substitutions such as `|release|` are not expanded, `include` and `only` are not resolved, and content autodoc generates from docstrings is not in the file, so none of it is linted. Comments still carry Vale's [directives](/formats/restructuredtext.md#comments), so `.. vale off` works inside a Sphinx project as anywhere else.

A project written in MyST goes through Vale's own [MyST](/formats/myst.md) reader, which applies the same rule and the same `[sphinx]` section to the directive and role syntax in Markdown.

## [Setting up](#setting-up)

Install `docutils` into the environment the project builds with, so that `rst2html` is on your `$PATH`:

```bash
$ pip install docutils
```

Vale finds the interpreter from the script and keeps one Docutils process warm per run, so a project of a few hundred pages converts in a second or two. Nothing about the project's `conf.py`, theme, or extensions has to be installed for Vale to run.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.vale.sh/formats/sphinx.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.