# 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](extend.md) are specifically designed to be extended by **`nmk`** projects and plugins.

---

## Paths and files

---

(docpath)=

### **`docPath`** -- Documentation input path

| Type | Default value     |
| ---- | ----------------- |
| str  | ${PROJECTDIR}/doc |

This is the input path where [sphinx](https://www.sphinx-doc.org/) will look for documentation files.

---

(docconfig)=

### **`docConfig`** -- Sphinx config file

| Type | Default value                      |
| ---- | ---------------------------------- |
| str  | {ref}`${docPath}<docpath>`/conf.py |

This is the [sphinx](https://www.sphinx-doc.org/) configuration file, that will be generated by **`nmk`**.

---

(docConfigTemplate)=

### **`docConfigTemplate`** -- Config file template

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

This item is the path to the [Jinja](https://jinja.palletsprojects.com/en/3.1.x/templates/) template used by **`nmk`** to generate the **`${docConfig}`** file.

---

(docIndex)=

### **`docIndex`** -- Resolved documentation index file

| Type       | Default value                                                                                                                                                                                                                                  |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| list[Path] | Generated by [**`nmk_base.resolvers.FilesResolver`**](https://nmk-base.readthedocs.io/en/stable/autoapi/nmk_base/resolvers/index.html#nmk_base.resolvers.FilesResolver)<br/>(looking for "index.md" file in {ref}`${docPath}<docpath>` folder) |

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

_<span style="color:green">Added in version 1.1.0</span>_

---

(docstaticinputs)=

### **`docStaticInputs`** -- Documentation input files (static ones)

| Type       | Default value                                                                                                                                                                                                                                |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| list[Path] | Generated by [**`nmk_base.resolvers.FilesResolver`**](https://nmk-base.readthedocs.io/en/stable/autoapi/nmk_base/resolvers/index.html#nmk_base.resolvers.FilesResolver)<br/>(looking for "\*.\*" files in {ref}`${docPath}<docpath>` folder) |

This is the list of all files contained in the {ref}`${docPath}<docpath>` folder.

---

(docinputs)=

### **`docInputs`** -- Documentation input files (all of them)

| Type       | Default value                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| list[Path] | [ {ref}`${docStaticInputs}<docstaticinputs>`, {ref}`${plantUmlOutputFiles}<plantUmlOutputFiles>`, {ref}`${docSnippetsOutputFiles}<docSnippetsOutputFiles>` ] |

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.

_<span style="color:orange">Changed in version 1.2.0</span>_ -- Previous default value was only including {ref}`${docStaticInputs}<docstaticinputs>` reference.

---

(docoutput)=

### **`docOutput`** -- Generated documentation folder

| Type | Default value                                                                                                 |
| ---- | ------------------------------------------------------------------------------------------------------------- |
| str  | **[${outputDir}](https://nmk-base.readthedocs.io/en/stable/config.html#outputdir-output-base-directory)**/doc |

This is the path where [sphinx](https://www.sphinx-doc.org/) will generate the documentation.

---

## Sphinx configuration

---

(docExtensions)=

### **`docExtensions`** -- Enabled sphinx extensions

| Type      | Default value           |
| --------- | ----------------------- |
| list[str] | ["myst_parser", "furo"] |

This is the list of the [sphinx](https://www.sphinx-doc.org/) extensions to be enabled in the config file. Default enabled ones are:

- [myst_parser](https://myst-parser.readthedocs.io/en/stable/index.html): used to support markdown (\*.md) files in documentation input
- [furo](https://pradyunsg.me/furo/): used to enable the **Furo** HTML theme for generated documentation

---

(docExtensionsVenvDeps)=

### **`docExtensionsVenvDeps`** -- Venv dependencies for sphinx extensions

| Type      | Default value |
| --------- | ------------- |
| list[str] | []            |

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

---

(docHtmlTheme)=

### **`docHtmlTheme`** -- HTML theme

| Type | Default value |
| ---- | ------------- |
| str  | furo          |

This item configures the enabled HTML theme for generated documentation.

_<span style="color:orange">Changed in version 1.1.0</span>_ -- Previous theme was **sphinx_rtd_theme**

---

(docName)=

### **`docName`** -- Document name

| Type | Default value                                                                                        |
| ---- | ---------------------------------------------------------------------------------------------------- |
| str  | **[${projectName}](https://nmk-base.readthedocs.io/en/stable/config.html#projectname-project-name)** |

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

---

(docAuthor)=

### **`docAuthor`** -- Document author

| Type | Default value                                                                                              |
| ---- | ---------------------------------------------------------------------------------------------------------- |
| str  | **[${projectAuthor}](https://nmk-base.readthedocs.io/en/stable/config.html#projectauthor-project-author)** |

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

---

(docVersion)=

### **`docVersion`** -- Document version

| Type | Default value                                                                                     |
| ---- | ------------------------------------------------------------------------------------------------- |
| str  | **[${gitVersion}](https://nmk-base.readthedocs.io/en/stable/config.html#gitversion-git-version)** |

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

_<span style="color:green">Added in version 1.1.0</span>_

---

(docYear)=

### **`docYear`** -- Document year

| Type | Default value                                                 |
| ---- | ------------------------------------------------------------- |
| str  | Generated by {py:class}`nmk_doc.resolvers.NmkDocYearResolver` |

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

---

(docExtraConfig)=

### **`docExtraConfig`** -- Extra configuration items

| Type | Default value |
| ---- | ------------- |
| dict | {}            |

This item allows the project and/or other plugins to contribute to [sphinx](https://www.sphinx-doc.org/) 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](https://readthedocs.org/), using the following configuration items.

---

(docRTDConfig)=

### **`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](https://readthedocs.org/), that will be generated by **`nmk`**.

See [Config file documentation](https://docs.readthedocs.io/en/stable/config-file/v2.html) for more information.

---

(docRTDConfigTemplate)=

### **`docRTDConfigTemplate`** -- Read The Docs build config file template

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

This is the template path to generate {ref}`${docRTDConfig}<docRTDConfig>` file.

---

(docRTDDisabled)=

### **`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](https://readthedocs.org/), if the project is just intended to be a local one, without publishing any external documentation.

---

(plantumlConfig)=

## PlantUML diagrams

This whole chapter was _<span style="color:green">Added in version 1.1.0</span>_

---

(plantUmlVersion)=

### **`plantUmlVersion`** -- PlantUML version

| Type | Default value |
| ---- | ------------- |
| str  | 1.2026.2      |

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

---

(plantUmlDownloadUrl)=

### **`plantUmlDownloadUrl`** -- PlantUML download URL

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

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

---

(plantUmlLocalPath)=

### **`plantUmlLocalPath`** -- PlantUML runtime path

| Type | Default value                                                                                                   |
| ---- | --------------------------------------------------------------------------------------------------------------- |
| str  | [${PROJECTDIR_NMK}](https://nmk.readthedocs.io/en/stable/file.html#built-in-config-items)/plantuml/plantuml.jar |

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

---

(plantUmlDiagramsFolder)=

### **`plantUmlDiagramsFolder`** -- PlantUML diagrams source folder

| Type | Default value                                                                                  |
| ---- | ---------------------------------------------------------------------------------------------- |
| str  | [${PROJECTDIR}](https://nmk.readthedocs.io/en/stable/file.html#built-in-config-items)/diagrams |

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

---

(plantUmlDiagrams)=

### **`plantUmlDiagrams`** -- PlantUML diagrams source files

| Type      | Default value                                                                                                                                                                                                                                                                |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| list[str] | Generated by [**`nmk_base.resolvers.FilesResolver`**](https://nmk-base.readthedocs.io/en/stable/autoapi/nmk_base/resolvers/index.html#nmk_base.resolvers.FilesResolver)<br/>(looking for "\*.puml" files in {ref}`${plantUmlDiagramsFolder}<plantUmlDiagramsFolder>` folder) |

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

---

(plantUmlOutputFolder)=

### **`plantUmlOutputFolder`** -- PlantUML generation folder

| Type | Default value                       |
| ---- | ----------------------------------- |
| str  | {ref}`${docPath}<docPath>`/diagrams |

This is the generation folder for **PlantUML** diagram image files.

---

(plantUmlOutputFormats)=

### **`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)=

### **`plantUmlOutputFiles`** -- PlantUML generated files

| Type      | Default value                                                          |
| --------- | ---------------------------------------------------------------------- |
| list[str] | Generated by {py:class}`nmk_doc.resolvers.PlantUmlOutputFilesResolver` |

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

---

(plantUmlExtraOptions)=

### **`plantUmlExtraOptions`** -- 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)=

### **`plantUmlReady`** -- PlantUML generation enablement

| Type | Default value                                                    |
| ---- | ---------------------------------------------------------------- |
| bool | Generated by {py:class}`nmk_doc.resolvers.DiagramsReadyResolver` |

This boolean flag is set to True if both:

- [${javaRuntime}](https://nmk-base.readthedocs.io/en/stable/config.html#javaruntime-resolved-java-command-path) is detected on the system
- {ref}`${plantUmlDiagrams}<plantUmlDiagrams>` input diagrams list is not empty

---

(plantUmlVsCodeSettings)=

### **`plantUmlVsCodeSettings`** -- PlantUML VSCode extension settings

| Type      | Default value                                                                                                                                                                 |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| list[str] | Generated by [nmk_base.resolvers.MultiChoiceResolver](https://nmk-base.readthedocs.io/en/stable/autoapi/nmk_base/resolvers/index.html#nmk_base.resolvers.MultiChoiceResolver) |

Enable extra VSCode **PlantUML** extension settings generation, if {ref}`${plantUmlReady}<plantUmlReady>` is True.

---

(snippetsConfig)=

## Snippets

This whole chapter was _<span style="color:green">Added in version 1.2.0</span>_

---

(docSnippetsOutputFolder)=

### **`docSnippetsOutputFolder`** -- Generated snippets output folder

| Type | Default value                       |
| ---- | ----------------------------------- |
| str  | {ref}`${docPath}<docPath>`/snippets |

This is the generation folder doc snippets.

---

(docSnippetsInputs)=

### **`docSnippetsInputs`** -- Extra inputs for snippets generation

| Type      | Default value |
| --------- | ------------- |
| list[str] | []            |

These are snippets inputs (list of files that cause snippets rebuild if changed).

---

(docSnippets)=

### **`docSnippets`** -- Snippets definition

| Type          | Default value |
| ------------- | ------------- |
| dict[str,str] | {}            |

This is the definition of snippets to be generated, as a map:

- keys are the generated file names, relative to {ref}`${docSnippetsOutputFolder}<docSnippetsOutputFolder>`
- values are command lines to be executed; stdout will be captured and written to the target file

Example:

```{literalinclude} ../src/tests/templates/ref_doc.yml
:language: yaml
```

This will generate a **doc/snippets/example_snippet.txt** snippet, containing the **`nmk`** help page.

---

(docSnippetsOutputFiles)=

### **`docSnippetsOutputFiles`** -- Generated snippet files

| Type      | Default value                                                             |
| --------- | ------------------------------------------------------------------------- |
| list[str] | Generated by {py:class}`nmk_doc.resolvers.DocSnippetsOutputFilesResolver` |

This is the list of expected generated snippet files, computed from {ref}`${docSnippets}<docSnippets>` snippets definition, and {ref}`${docSnippetsOutputFolder}<docSnippetsOutputFolder>` output folder.