mkdocs for product documentation

start with installation

We can either use existing python virtual environment or create a new one for this exercise

using pip

pip install mkdocstrings

with conda

conda install -c conda-forge mkdocstrings

Theme installation

pip install mkdocs-material

For detail usage of theme with mkdocs refer this link

Once all the installation is done in the virtual environment

start with following steps:

• open the command prompt window with activated virtual environment or the shell window with activated environment.

• Go to project folder structure via command window, where we want to start the documentation. Ideally it is the root of the folder structure.

• Run -> mkdocs new <project-name> in the terminal window

• It will create following folder and yaml file.
  

Quick usage

# mkdocs.yml
theme:
  name: "material"

plugins:
- search
- mkdocstrings

Within the docs folder create markdown file and following

# Reference

::: my_library.my_module.my_class

After you have added the class or function name in the markdown file run the following command from terminal to see it in action.

mkdocs serve- open the browser and type http://localhost:8000 url to see the documentation in action.
mkdocs build - to generate the static html site source code
mkdocs help - to get help on mkdocs

We are majorly using combination of these 3 packages

• mkdocstrings - To generate autodocumentation using docstrings from class and python functions
• mkdocs - To generate and build html site from markdown files
• mkdocs-material theme To apply visually appealing theme to our documentation style.

References

mkdocs website
mkdocstrings usage guide
mkdocs-material-theme