Writing documentation and user guides¶

We use Sphinx, and a few add-ons, most importantly nbsphinx so we can write using Jupyter notebooks.

Organisation¶

The documentation mainly lives in the docs/source folder. This is the “relevant” high-level folder structure for the documentation:

├── docs                      <- Documentation folder.
│   ├── build                 <- Placeholder for built docs.
│   ├── source                <- Documentation scripts.
│   │   ├── api               <- Files to render docstrings.
│   │   ├── basics / websites <- Walkthrough notebooks.
│   │   ├── index.rst         <- Main file.
│   │   ├── contributing...   <- How to docs.
│   │   └── etc.
│   └── etc.                  <- Other necessary files.
│
└── etc.

Serving documentation locally¶

It can be helpful to build and serve the documentation locally in order to QA any changes.

To do so:

Clone the repository

git clone git@github.com:cmagovuk/selene-core.git

Activate your relevant environment
```
conda activate py39
```
Navigate to the docs directory (the one with the Makefile), install requirements, pull submodules and build the html
```
cd selene-core/docs
make requirements
make html
```
Run the docker image which serves the documentation
```
make serve-start
```
For CMA users, in the browser URL, navigate to https://data.cma.gov.uk/leda/user/USERNAME/INSTANCENAME/proxy/80/index.html
Update the documentation, re-run make html and refresh the page.
To stop the container, run
```
make serve-stop
```

[ ]: