# Usage

To use this plugin in your **`nmk`** project, insert this reference in your **nmk.yml** main file:

```yaml
refs:
  - pip://nmk-doc!plugin.yml
```

Then you can start writing documentation by adding an **index.md** file in your project **doc** sub-folder. Once done, **`nmk`** build will:

- generate the [sphinx](https://www.sphinx-doc.org/) **conf.py** file in the **doc** sub-folder
- build the documentation; you can check the result by browsing the **out/doc/index.html** file

This plugin also enables images generation from [PlantUML](https://plantuml.com/) diagrams. If you add some **.puml** diagram files in your project **diagrams** sub-folder, **`nmk`** build will:

- download the **PlantUML** runtime
- generate all images from your **.puml** diagrams; you can check the result by browsing the **doc/diagrams** folder

```{note}
**PlantUML** is a **java** application, so **java** needs to be installed on your system. See [nmk-base **java** handling](https://nmk-base.readthedocs.io/en/stable/config.html#java-runtime) for more information on how **java** is detected.

However if **java** is not detected, the build won't fail (a warning will be displayed instead).
```

Here is an example of an image generated from a **PlantUML** diagram:

![](./diagrams/my-sample-diagram.svg)

Diagram source code:

```{include} ../diagrams/example.puml
:literal:
```