## Sphinx Documentation

### View the Docs

For our documentation we use [Sphinx-docs](https://www.sphinx-doc.org/en/master/)
and lives in the [./docs](https://github.com/openstax/corgi/tree/main/docs) directory.

If you are currently running the entire stack you should be able to see the
documentation by visiting [http://localhost:8000](http://localhost:8000).

The documentation is configured to watch for changes and re-build the documentation.
This allows developers the ability to preview their documentation changes as they
make them.

If you would like to run the documentation without the entire stack running you
can do so by running:

    docker-compose up docs

### Editing The Docs

Edits are done in restructured text (rst).

While editing, you can check the logs by running
```
$ ./corgi docs logs
```
or
```
$ ./corgi docs logs -f
```

If edits have been made to the Navigation and are not reflected, re-build the docker image:
```
$ ./corgi build <stack-name>
$ ./corgi start [stack-name]
```

### Auto-generated docs

Additional documentation is automatically pulled from this README and added to the sphinx docs when the docs service is running and when corgi.readthedocs.io is deployed. Each level 2 header (##) becomes a separate page in the sphinx docs. Links, like [README.md](https://github.com/openstax/corgi/tree/main/README.md), are resolved to github links relative to the markdown file's parent directory.

This documentation is stored in [docs/auto](https://github.com/openstax/corgi/tree/main/docs/auto) and this directory should not be modified directly. It is saved as markdown and converted with the m2r2 sphinx extension (see [conf.py](https://github.com/openstax/corgi/tree/main/docs/conf.py) for more information).

When the files are generated, they are numbered so that the glob result will match the order the headers occurred in within the README.

The `docs` docker image uses [watchdog](https://pypi.org/project/watchdog/) to automatically update the auto-generated documentation as you update [README.md](https://github.com/openstax/corgi/tree/main/README.md).

There is a pre_build step in [.readthedocs.yaml](https://github.com/openstax/corgi/tree/main/.readthedocs.yaml) that generates the documentation during deployment.