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

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

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

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

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)=
### **`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", "sphinx_rtd_theme"]

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
* [sphinx_rtd_theme](https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html): used to enable the [ReadTheDocs](https://readthedocs.org/) 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`** -- 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}](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`** -- 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.

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