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.

`docIndex` – Resolved documentation index file¶

Type	Default value
list[Path]	Generated by `nmk_base.resolvers.FilesResolver` (looking for “index.md” file in ${docPath} folder)

Checks if the index file (index.md) exists in the ${docPath} folder. This is typically use to enable (or not) documentation tasks.

Added in version 1.1.0

`docStaticInputs` – Documentation input files (static ones)¶

Type	Default value
list[Path]	Generated by `nmk_base.resolvers.FilesResolver` (looking for “.” files in ${docPath} folder)

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”, “furo”]

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
furo: used to enable the Furo 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	furo

This item configures the enabled HTML theme for generated documentation.

Changed in version 1.1.0 – Previous theme was sphinx_rtd_theme

`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.

`docVersion` – Document version¶

Type	Default value
str	${gitVersion}

This item is used to configure the main document version. Default value is the project git detected version.

Added in version 1.1.0

`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.

PlantUML diagrams¶

This whole chapter was Added in version 1.1.0

`plantUmlVersion` – PlantUML version¶

Type	Default value
str	1.2026.2

This is the PlantUML version that will be used to generate diagrams.

`plantUmlDownloadUrl` – PlantUML download URL¶

Type	Default value
str	https://github.com/plantuml/plantuml/releases/download/v${plantUmlVersion}/plantuml-mit-${plantUmlVersion}.jar

This is the URL from which the PlantUML runtime will be downloaded.

`plantUmlLocalPath` – PlantUML runtime path¶

Type	Default value
str	${PROJECTDIR_NMK}/plantuml/plantuml.jar

This is the local path where the PlantUML runtime will be downloaded.

`plantUmlDiagramsFolder` – PlantUML diagrams source folder¶

Type	Default value
str	${PROJECTDIR}/diagrams

This is the folder from which PlantUML diagrams source files will be resolved.

`plantUmlDiagrams` – PlantUML diagrams source files¶

Type	Default value
list[str]	Generated by `nmk_base.resolvers.FilesResolver` (looking for “*.puml” files in ${plantUmlDiagramsFolder} folder)

This is the list of PlantUML diagram source files to be processed.

`plantUmlOutputFolder` – PlantUML generation folder¶

Type	Default value
str	${docPath}/diagrams

This is the generation folder for PlantUML diagram image files.

`plantUmlOutputFormats` – PlantUML output formats¶

Type	Default value
list[str]	[ “svg” ]

This is the list of output file formats to be generated from PlantUML diagram files.

`plantUmlOutputFiles` – PlantUML generated files¶

Type	Default value
list[str]	Generated by `nmk_doc.resolvers.PlantUmlOutputFilesResolver`

This is the list of expected generated files by PlantUML, computed from diagram names parsed from ${plantUmlDiagrams} input files, and ${plantUmlOutputFormats} list of output formats

`plantUmlOutputFiles` – PlantUML command line options¶

Type	Default value
str	–verbose –skip-fresh –check-before-run

This string is used as extra command line options when invoking PlantUML runtime to generate files from input diagrams.

`plantUmlReady` – PlantUML generation enablement¶

Type	Default value
bool	Generated by `nmk_doc.resolvers.DiagramsReadyResolver`

This boolean flag is set to True if both:

${javaRuntime} is detected on the system
${plantUmlDiagrams} input diagrams list is not empty

`plantUmlVsCodeSettings` – PlantUML VSCode extension settings¶

Type	Default value
list[str]	Generated by nmk_base.resolvers.MultiChoiceResolver

Enable extra VSCode PlantUML extension settings generation, if ${plantUmlReady} is True.

Configuration Reference¶

Paths and files¶

docPath – Documentation input path¶

docConfig – Sphinx config file¶

docConfigTemplate – Config file template¶

docIndex – Resolved documentation index file¶

docStaticInputs – Documentation input files (static ones)¶

docInputs – Documentation input files (all of them)¶

docOutput – Generated documentation folder¶

Sphinx configuration¶

docExtensions – Enabled sphinx extensions¶

docExtensionsVenvDeps – Venv dependencies for sphinx extensions¶

docHtmlTheme – HTML theme¶

docName – Document name¶

docAuthor – Document author¶

docVersion – Document version¶

docYear – Document year¶

docExtraConfig – Extra configuration items¶

Read The Docs configuration¶

docRTDConfig – Read The Docs build config file¶

docRTDConfigTemplate – Read The Docs build config file template¶

docRTDDisabled – Read The Docs build enablement¶