Documentation

• Documentation is written in markdown format and files are kept in the /docs directory in the project root.
• API documentation is auto-generated by the mkdocstrings package. An example of this can be seen in the reference.md file.
• New files must be added to the table of context in /mkdocs.yml.

Develop

1. Make changes on a development branch

2. Run the following command to render and serve documentation locally

   docker-compose run --rm --service-ports mkdocs
   

3. Visit the local documentation to see your changes while developing
   http://localhost:8000

4. Push this branch, get approval and merge to the main branch

Publish

1. Pull down the gh-pages branch. This only needs to be done once

   git checkout --track origin/gh-pages
   

2. Run the publish_documentation script

   ./publish_documentation.sh
   

3. Visit the hosted documentation
   https://wayfair-incubator.github.io/extra-model/site/