// Use when generating or auditing documentation in Sphinx format — covers config, directory structure, frontmatter conventions, and build commands.
Use when generating or auditing documentation in Docusaurus format — covers config, directory structure, frontmatter conventions, and build commands.
Use when generating or auditing documentation in MkDocs format — covers config, directory structure, frontmatter conventions, and build commands.
Use when generating or auditing documentation in plain Markdown format — covers config, directory structure, frontmatter conventions, and build commands.
Use when generating or auditing documentation in VitePress format — covers config, directory structure, frontmatter conventions, and build commands.
Use when writing, auditing, or generating documentation for projects in unsupported languages — covers docstring conventions, API doc extraction, and generic heuristic patterns.
Use when writing, auditing, or generating documentation for Go projects — covers docstring conventions, API doc extraction, and Go-specific patterns.
| name | fw-sphinx |
| description | Use when generating or auditing documentation in Sphinx format — covers config, directory structure, frontmatter conventions, and build commands. |
Detected when conf.py exists and contains Sphinx-related configuration (e.g., extensions list, master_doc, or project variable).
Key fields to extract from conf.py:
# conf.py
project = 'My Project'
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.viewcode',
]
master_doc = 'index' # default: 'index'
source_suffix = '.rst' # or ['.rst', '.md'] with MyST
extensions: active Sphinx extensions (especially autodoc, napoleon)source_suffix: determines if docs are .rst, .md (MyST), or bothmaster_doc: root document (default index)Directory containing conf.py. Common patterns:
docs/source/ (with docs/build/ for output)docs/ (flat layout)Sphinx uses toctree directives for navigation:
.. toctree::
:maxdepth: 2
:caption: Contents
getting-started
api/index
guides/deployment
Each entry is a document name (without extension) relative to the doc root.
Parse toctree entries in index.rst and sub-indexes. Each entry maps to a file in the doc root.
If sphinx.ext.autodoc is enabled, check for:
.. automodule:: mypackage.auth
:members:
This auto-generates docs from Python docstrings. The source module mypackage.auth maps to mypackage/auth.py.
| Source | Doc Candidate |
|---|---|
src/auth/login.py | docs/source/api/auth.rst |
mypackage/utils.py | docs/source/api/utils.rst |
Auth Module
===========
Brief description of the module.
.. module:: mypackage.auth
API Reference
-------------
.. function:: login(username, password)
Authenticates a user and returns a session token.
:param str username: The user's login name.
:param str password: The user's password.
:returns: An authenticated session object.
:rtype: Session
:raises AuthError: If credentials are invalid.
Example::
session = login("admin", "secret")
.. class:: Session
Represents an authenticated user session.
.. attribute:: token
:type: str
The session JWT token.
If MyST parser is enabled (myst_parser in extensions):
# Auth Module
Brief description.
```{automodule} mypackage.auth
:members:
login(username, password)Authenticates a user.
Use environment variables for credentials.
## Sphinx-Specific Content
Valid Sphinx content — do not flag as quality issues:
- `.. directive::` syntax (reStructuredText directives)
- `:role:` inline roles (e.g., `:func:`, `:class:`, `:ref:`)
- `.. code-block::` with language specifiers
- `.. note::`, `.. warning::`, `.. deprecated::` admonitions
- Cross-references like `` :func:`mypackage.auth.login` ``
- MyST `{directive}` syntax in `.md` files