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
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
, andhtml_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