# Document writing

We use [Sphinx](http://www.sphinx-doc.org/en/stable/) to generate our documentation.

And if you want to contribute to our documentation, you can follow the steps below.

## Install and Build

1. Install dependencies

   ```bash
       cd docs
       pip install -r requirements.txt
   ```

2. Build documentation

   ```bash
       cd docs
       make all-html
   ```
   
   or run this command in CALYPSO package root.

   ```bash
       make manual
   ```

## Syntax

### User Documents

We use [MyST-Parser](https://myst-parser.readthedocs.io) to write our documentation.
If you want to write a document for user. You should check the syntax of [MyST-Parser](https://myst-parser.readthedocs.io) before writing.

### API Documents

We use [numpydoc](https://numpydoc.readthedocs.io/) to automatically generate api documentation.
Only write numpydoc string in your codes and obey [numpydoc style](https://numpydoc.readthedocs.io/en/latest/format.html).

:::{card} A example

```{literalinclude} example.py
```

+++

```{eval-rst}
.. automodule:: example
   :members:
   :undoc-members:
   :show-inheritance:
```

:::

## Tool

vscode extension: [MyST-Markdown](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight)
vscode extension: [autoDocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring)