Sphinx

https://www.sphinx-doc.org/en/master/
Admin
Sphinx is a powerful documentation generator tool for Python projects that creates professional...
Tokens:451,349
Snippets:4,030
Trust Score:9.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Run sphinx-quickstart to create documentation layout

Source: https://www.sphinx-doc.org/en/master/tutorial/getting-started.html

Run this command to start the interactive setup for the documentation project. You will be prompted to answer several questions to configure the project.

```bash
(.venv) $ sphinx-quickstart docs

```

--------------------------------

### Set up environment with pip

Source: https://www.sphinx-doc.org/en/master/internals/contributing.html

Alternative environment setup using pip: creates a virtual environment, activates it, and installs the package in editable mode.

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .

```

--------------------------------

### Sphinx Example Configuration File

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Example Sphinx configuration file (conf.py) showing project information, general configuration, and HTML output options. Use as a starting point for a Sphinx project; adjust values like project, copyright, and extensions as needed.

```python
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'Test Project'
copyright = '2000-2042, The Test Project Authors'
author = 'The Authors'
version = release = '4.16'

# -- General configuration ------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

exclude_patterns = [
    '_build',
    'Thumbs.db',
    '.DS_Store',
]
extensions = []
language = 'en'
master_doc = 'index'
pygments_style = 'sphinx'
source_suffix = '.rst'
templates_path = ['_templates']

# -- Options for HTML output ----------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']

```

--------------------------------

### Install Transifex CLI tool

Source: https://www.sphinx-doc.org/en/master/usage/advanced/intl.html

Installs the Transifex CLI tool. The official installation process places the tx binary in the current directory along with a README and a LICENSE file, and adds the current directory to $PATH.

```bash
$ curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash

```

--------------------------------

### Install Sphinx from source (clone)

Source: https://www.sphinx-doc.org/en/master/usage/installation.html

Install Sphinx from a local clone of the Git repository.

```bash
$ git clone https://github.com/sphinx-doc/sphinx
$ cd sphinx
$ pip install .

```

--------------------------------

### Configure extensions list with third-party extension

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Add a third-party extension to the extensions list. The extension must be installed and included in the list.

```python
extensions = [
    ...
    'numpydoc',
]

```

--------------------------------

### Configure html_additional_pages

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Maps document names to additional templates rendered as HTML pages. The example renders the template 'custom-download.html.jinja' as the page 'download.html'.

```python
html_additional_pages = {
    'download': 'custom-download.html.jinja',
}

```

--------------------------------

### linkcheck_auth configuration example

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Configure authentication for the linkcheck builder. The first matching entry in the list takes priority, and values can be any object understood by the requests library.

```python
linkcheck_auth = [
  ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
  ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
]

```

--------------------------------

### Configure highlight_options for Pygments lexers

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Configuration dictionary for Sphinx's highlight_options option. Maps Pygments lexer names to lexer-specific options; the example sets stripall for the default lexer and startinline for PHP.

```python
highlight_options = {
  'default': {'stripall': True},
  'php': {'startinline': True},
}

```

--------------------------------

### Set copyright with %Y placeholder

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Examples of copyright statements using the '%Y' placeholder, which is replaced with the current four-digit year.

```python
copyright = '%Y'
```

```python
copyright = '%Y, Author Name'
```

```python
copyright = 'YYYY-%Y, Author Name'
```

--------------------------------

### Configure html_domain_indices

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Specifies which domain-specific indices to generate. The example includes the Python module index by its name 'py-modindex'.

```python
html_domain_indices = {
    'py-modindex',
}

```

--------------------------------

### Set epub_guide metadata

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Defines metadata for the guide element of content.opf. Each tuple contains type, URI, and title. Default entries for cover and toc types are automatically inserted unless explicitly overwritten.

```python
epub_guide = (
    ('cover', 'cover.html', 'Cover Page'),
)

```

--------------------------------

### linkcheck_case_insensitive_urls example for all URLs

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Treat all URLs as case-insensitive for link checking. Note that URI fragments (HTML anchors) are always checked case-sensitively.

```python
linkcheck_case_insensitive_urls = ['.*']

```

--------------------------------

### Set extension version requirements with needs_extensions

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Specify version requirements for extensions in the extensions list. The version strings should be in 'major.minor' form. The extension must declare its version in its setup() function.

```python
needs_extensions = {
    'sphinxcontrib.something': '1.5',
}

```

--------------------------------

### linkcheck_case_insensitive_urls example for GitHub

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Treat all GitHub URLs as case-insensitive for link checking. URLs matching these patterns are reported as 'working' instead of 'redirected' when casing differs.

```python
linkcheck_case_insensitive_urls = [
    r'https://github\.com/.*',
]

```

--------------------------------

### linkcheck_allowed_redirects example

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Configure the linkcheck builder to treat redirects as working when the source URI matches the key pattern and the redirect location matches the value pattern. Redirects that do not match these rules produce a warning, which can be useful with fail-on-warnings mode.

```python
linkcheck_allowed_redirects = {
    # All HTTP redirections from the source URI to
    # the canonical URI will be treated as "working".
    r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
}

```

--------------------------------

### Copy dotfiles with html_static_path

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Explicitly list dotfiles under html_static_path to copy them, since dotfiles are not copied by default for security reasons. This example includes a .htaccess file. Alternatively, use html_extra_path to copy dotfiles.

```python
html_static_path = ['_static', '_static/.htaccess']

```

--------------------------------

### linkcheck_request_headers configuration example

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Set custom HTTP request headers for specific hosts or all hosts using the '*' wildcard. The wildcard matches only when no other host-specific setting matches.

```python
linkcheck_request_headers = {
    "https://www.sphinx-doc.org/": {
        "Accept": "text/html",
        "Accept-Encoding": "utf-8",
    },
    "*": {
        "Accept": "text/html,application/xhtml+xml",
    }
}

```

--------------------------------

### linkcheck_ignore example

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Ignore URIs matching the given regular expression during linkcheck builds. Server-issued redirects that match ignored URIs will not be followed.

```python
linkcheck_ignore = [r'https://localhost:\d+/']

```

--------------------------------

### Configure manpages_url for different manpage sites

Source: https://www.sphinx-doc.org/en/master/usage/configuration.html

Set manpages_url to a URL pattern for cross-referencing manpage roles. The patterns available are {page}, {section}, and {path}. Examples for Debian, man7.org, linux.die.net, and helpmanual.io are shown.

```python
# To use manpages.debian.org:
manpages_url = 'https://manpages.debian.org/{path}'
# To use man7.org:
manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.html'
# To use linux.die.net:
manpages_url = 'https://linux.die.net/man/{section}/{page}'
# To use helpmanual.io:
manpages_url = 'https://helpmanual.io/man{section}/{page}'

```

--------------------------------

### get_translation function with usage example

Source: https://www.sphinx-doc.org/en/master/_modules/sphinx/locale.html

Returns a translation function for the given catalog and namespace. The docstring includes an example of how extensions can use this API to translate messages, including adding a message catalog in setup.

```python
def get_translation(catalog: str, namespace: str = 'general') -> Callable[[str], str]:
    """Get a translation function based on the *catalog* and *namespace*.

    The extension can use this API to translate the messages on the
    extension::

        from pathlib import Path
        from sphinx.locale import get_translation

        MESSAGE_CATALOG_NAME = 'myextension'  # name of *.pot, *.po and *.mo files
        _ = get_translation(MESSAGE_CATALOG_NAME)
        text = _('Hello Sphinx!')


        def setup(app):
            package_dir = Path(__file__).resolve().parent
            locale_dir = package_dir / 'locales'
            app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)

    With this code, sphinx searches a message catalog from
    ``${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo``.
    The :confval:`language` is used for the searching.

    .. versionadded:: 1.8
    """

    def gettext(message: str) -> str:
        if not is_translator_registered(catalog, namespace):
            # not initialized yet
            return _TranslationProxy(catalog, namespace, message)  # type: ignore[return-value]
        else:
            translator = get_translator(catalog, namespace)
            return translator.gettext(message)

    return gettext
```

--------------------------------

### Run sphinx-quickstart

Source: https://www.sphinx-doc.org/en/master/usage/quickstart.html

Run the sphinx-quickstart script to set up a source directory and create a default conf.py with the most useful configuration values from a few questions it asks you.

```bash
$ sphinx-quickstart

```

--------------------------------

### productionlist directive example

Source: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html

Example of the productionlist directive showing try_stmt grammar productions. Each production is on a single line with continuation lines starting with a colon. Token names in interpreted text generate cross-references.

```restructuredtext
.. productionlist::
   try_stmt: try1_stmt | try2_stmt
   try1_stmt: "try" ":" `suite`
            : ("except" [`expression` ["," `target`]] ":" `suite`)+
            : ["else" ":" `suite`]
            : ["finally" ":" `suite`]
   try2_stmt: "try" ":" `suite`
            : "finally" ":" `suite`

```

--------------------------------

### Sphinx.setup_extension()

Source: https://www.sphinx-doc.org/en/master/extdev/appapi.html

Sets up an extension by importing and initializing it.

```APIDOC
## Sphinx.setup_extension()

### Description
Sets up an extension by importing and initializing it.

### Method
setup_extension

### Parameters
- **name** (string) - Required - The name of the extension to set up.

```

--------------------------------

### Set up environment with uv sync

Source: https://www.sphinx-doc.org/en/master/internals/contributing.html

Sets up the development environment by synchronizing dependencies with uv.

```bash
uv sync

```

--------------------------------

### Register a custom directive with app.add_directive

Source: https://www.sphinx-doc.org/en/master/_modules/sphinx/application.html

Example of registering a custom Docutils directive with Sphinx. The directive class defines required arguments, options, and a run method. The setup function calls app.add_directive to register it.

```python
from docutils.parsers.rst import Directive, directives

class MyDirective(Directive):
    has_content = True
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = True
    option_spec = {
        'class': directives.class_option,
        'name': directives.unchanged,
    }

    def run(self):
        pass

def setup(app):
    app.add_directive('my-directive', MyDirective)
```

--------------------------------

### Set up virtual environment and install Sphinx

Source: https://www.sphinx-doc.org/en/master/tutorial/getting-started.html

Run these commands in the terminal to create a Python virtual environment, activate it, and install Sphinx. The commands assume you are in the directory you created.

```bash
$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install sphinx

```
Tokens:
Raw