Configuration Reference

The nmk-doc plugin handles the configuration items listed in this page.

All of them are initiliazed with convenient default values, so that you don’t need to setup them for a default working behavior. You can anyway override them in your project if you need to fine tune the plugin behavior. Some items are specifically designed to be extended by nmk projects and plugins.

Paths and files

docPath – Documentation input path

Type	Default value
str	${PROJECTDIR}/doc

This is the input path where sphinx will look for documentation files.

docConfig – Sphinx config file

Type	Default value
str	${docPath}/conf.py

This is the sphinx configuration file, that will be generated by nmk.

docConfigTemplate – Config file template

Type	Default value
str	${BASEDIR}/templates/config.py.jinja

This item is the path to the Jinja template used by nmk to generate the ${docConfig} file.

docStaticInputs – Documentation input files (static ones)

Type	Default value
list[Path]	Generated by nmk_doc.resolvers.NmkDocInputsResolver

This is the list of all files contained in the ${docPath} folder.

docInputs – Documentation input files (all of them)

Type	Default value
list[Path]	[ ${docStaticInputs} ]

This is the list of all files that contribute to the documentation build. It is used to perform documentation incremental build (i.e. nmk will rebuild documentation only if at least one of these files changed).

This item is welcomed to be extended by other plugins, typically to include source files that may be parsed for automated documentation generation.

docOutput – Generated documentation folder

Type	Default value
str	${outputDir}/doc

This is the path where sphinx will generate the documentation.

Sphinx configuration

docExtensions – Enabled sphinx extensions

Type	Default value
list[str]	[“myst_parser”, “sphinx_rtd_theme”]

This is the list of the sphinx extensions to be enabled in the config file. Default enabled ones are:

• myst_parser: used to support markdown (*.md) files in documentation input

• sphinx_rtd_theme: used to enable the ReadTheDocs HTML theme for generated documentation

docExtensionsVenvDeps – Venv dependencies for sphinx extensions

Type	Default value
list[str]	[]

List of extra python venv dependencies required to enable declared sphinx extensions

docHtmlTheme – HTML theme

Type	Default value
str	sphinx_rtd_theme

This item configures the enabled HTML theme for generated documentation.

docName – Document name

Type	Default value
str	${projectName}

This item is used to configure the main document name. Default value is the project name.

docAuthor – Document author

Type	Default value
str	${projectAuthor}

This item is used to configure the document author. Default value is the project author.

docYear – Document year

Type	Default value
str	Generated by nmk_doc.resolvers.NmkDocYearResolver

This item configures the document generation year. Default is the current one.

docExtraConfig – Extra configuration items

Type	Default value
dict	{}

This item allows the project and/or other plugins to contribute to sphinx config file generation. All items in this dict will be added to generated config file.

Read The Docs configuration

This plugin also enable automated configuration for documentation build on Read The Docs, using the following configuration items.

docRTDConfig – Read The Docs build config file

Type	Default value
str	${PROJECTDIR}/.readthedocs.yaml

This is the automated build configuration file for Read The Docs, that will be generated by nmk.

See Config file documentation for more information.

docRTDConfigTemplate – Read The Docs build config file template

Type	Default value
str	${BASEDIR}/templates/readthedocs.yaml.jinja

This is the template path to generate ${docRTDConfig} file.

docRTDDisabled – Read The Docs build enablement

Type	Default value
bool	False

This boolean flag allows to disable config file and badge generation for Read The Docs, if the project is just intended to be a local one, without publishing any external documentation.