Documentation Tools

Project uses mkdocs and mkdocs-material to maintain the documentation on github pages.
Github page deployments are automated via github-actions - page-build-deployment and Update GH Pages, which get executed everytime a branch with documentation changes is merged into the main branch
Documentation versioning is implemented using the mike tool.

Mike Tool Usage

To push the version to github using mike tool, ensure that code is checked out locally using HTTP.

Warning

Mike tool doesn't work if code is checked out locally with SSH
Make sure page-build-deployment and Update GH Pages are working
Note

Mike tool works with Github Pages(gh-pages), versioning changes will appear only after they are deployed to gh-pages via github actions. To run them locally, use the following command to view documentation at http://localhost:8000/
```
mike serve
```
Install mike tool on local development environment
```
pip install mike
```
Make the documentation changes and check in the code.
Alias for documentation default version is set as latest. If required, this can be changed -
```
mike set-default --push latest
```
Publish a new version of project documentation by choosing a version identifier and update the alias set as the default version with -
```
mike deploy --push --update-aliases 0.1 latest
```
Every version will be deployed as a subdirectory of site_url set in mkdocs.yaml. Example the documentation will be published to URLs such as:
```
https://intel-retail.github.io/automated-self-checkout/0.1/
https://intel-retail.github.io/automated-self-checkout/0.2/
```
After PR is merged into the main branch, github actions will deploy the gh-pages and version dropdown on the documentation page will populate the new version as shown below
To delete versions, use the following commands -
```
mike delete [version identifier]...
```
To list versions, use the following commands -
```
mike list
```