Documentation

docs_dir

The directory containing the docs code of the project.

Example:

docs_dir: docs

Required: no

Default: doc-source

Type: String

enable_docs

Whether documentation should be built and deployed.

Example:

enable_docs: True

Required: no

Default: True

Type: Boolean

extra_sphinx_extensions

A list of additional extensions to enable for Sphinx.

Example:

extra_sphinx_extensions:
  - "sphinxcontrib.httpdomain"

These must also be listed in doc-source/requirements.txt.

Required: no

Default: [ ]

Type: Sequence of String

html_context

A dictionary of configuration values for the documentation HTML context.

String values must be encased in quotes.

Example:

html_context:
  display_github: True
  github_user: "'domdfcoding'"

Required: no

Default: { }

Type: Mapping of String to anything

html_theme_options

A dictionary of configuration values for the documentation HTML theme.

String values must be encased in quotes.

Example:

html_theme_options:
  logo_only: False
  fixed_sidebar: "'false'"
  github_type: "'star'"

Required: no

Default: { }

Type: Mapping of String to anything

intersphinx_mapping

A list of additional entries for intersphinx_mapping for Sphinx.

Each entry must be enclosed in double quotes.

Example:

intersphinx_mapping:
  - "'rtd': ('https://docs.readthedocs.io/en/latest/', None)"

Required: no

Default: [ ]

Type: Sequence of String

preserve_custom_theme

Whether custom documentation theme styling in _static/style.css and _templates/layout.html should be preserved.

Example:

preserve_custom_theme: True

Required: no

Default: False

Type: Boolean

rtfd_author

The name of the author to show on ReadTheDocs, if different.

Example:

rtfd_author: Dominic Davis-Foster and Joe Bloggs

Required: no

Default: The value of author

Type: String

sphinx_conf_epilogue

Like sphinx_conf_preamble, but the lines are inserted at the end of the file.

Indent lines with a single tab to form part of the setup function.

Required: no

Default: [ ]

Type: Sequence of String

sphinx_conf_preamble

A list of lines of Python code to add to the top of conf.py.

These could be additional settings for Sphinx or calls to extra scripts that must be executed before building the documentation.

Example:

sphinx_conf_preamble:
  - "import datetime"
  - "now = datetime.datetime.now()"
  - "strftime = now.strftime('%H:%M')"
  - "print(f'Starting building docs at {strftime}.')"

Required: no

Default: [ ]

Type: Sequence of String

sphinx_html_theme

The HTML theme to use for Sphinx.

Also adds the appropriate values to extra_sphinx_extensions, html_theme_options, and html_context_options.

Example:

sphinx_html_theme: alabaster

Currently, the supported themes are sphinx_rtd_theme, domdf_sphinx_theme, alabaster, and furo.

Required: no

Default: domdf-sphinx-theme

Type: ‘sphinx_rtd_theme’ or ‘sphinx-rtd-theme’ or ‘alabaster’ or ‘repo_helper_sphinx_theme’ or ‘repo-helper-sphinx-theme’ or ‘domdf_sphinx_theme’ or ‘domdf-sphinx-theme’ or ‘furo’

Allowed values: sphinx_rtd_theme, sphinx-rtd-theme, alabaster, repo_helper_sphinx_theme, repo-helper-sphinx-theme, domdf_sphinx_theme, domdf-sphinx-theme, furo

standalone_contrib_guide

Whether the contributing guide for the documentation should be a standlone page.

Example:

standalone_contrib_guide: True

Required: no

Default: False

Type: Boolean

docs_url

The URL of the documentation, if it uses a custom domain. Default https://{repo_name}.readthedocs.io.

Example:

docs_url: docs.repo-helper.uk

Required: no

Default: None

Type: String

docs_fail_on_warning

Whether the documentation check on GitHub Actions should fail on warnings.

Example:

docs_fail_on_warning: True

New in version 2021.2.18.

Required: no

Default: False

Type: Boolean