Documentation¶

Panda Docs¶

Contributions to docs, translations, proofreading, etc. is always welcome.

This project uses

Markdown for easy content creation,
MkDocs with some plugins for website generation,
Read the Docs for automated versioning, hosting, and search API.

The easiest way to preview Panda's documentation is using Docker.

GNU/Linux & Unix

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

Windows

docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material

See the fancy Material for MkDocs documentation for details.

Settings for Read the Docs can be changed in .readthedocs.yml.

Docs layout¶

The Panda documentation follows a common structure.

.
├── AUTHORS
├── CODE_OF_CONDUCT.md
├── mkdocs.yml
├── docs
│   ├── AUTHORS -> ../AUTHORS
│   ├── CODE_OF_CONDUCT.md -> ../CODE_OF_CONDUCT.md
│   ├── documentation.md
│   ├── index.md -> ../README.md
│   ├── LICENSE.md -> ../LICENSE.md
│   └── requirements.txt
├── LICENSE.md
└── README.md

The meaning of the files is probably self-explaining.

mkdocs.yml    # The docs configuration file
docs/
    index.md  # The documentation homepage
    ...       # Other markdown pages, images and other files

Docs management¶

This list contains useful commands for taking care of Panda's documentation.

On some systems we need to replace python with python3 and pip with pip3 --user. We should avoid using sudo. In some cases the following might help.

sudo ln -sv /usr/bin/pip3 /usr/local/bin/pip

Update the Python package manager.

pip install --upgrade pip setuptools wheel

Get required Python packages.
```
pip install -r requirements.txt
```
Start the live-reloading docs server.
```
mkdocs serve
```
Build the documentation site.
```
mkdocs build
```
Print this help message.
```
mkdocs --help
```

MkDocs installation¶

To get familiar with all required packages, installing one by one might be a helpful alternative.

Install the MkDocs package.
```
pip install mkdocs
```
Install the MkDocs Material theme.
```
pip install mkdocs-material
```
Install the MkDocs Material extensions.
```
pip install mkdocs-material-extensions
```
Install the PyMdown extensions.
```
pip install pymdown-extensions
```

Install the Awesome Pages plugin.

pip install mkdocs-awesome-pages-plugin

Install the Last Update plugin.

pip install mkdocs-git-revision-date-localized-plugin

Install the Minify HTML and JS plugin.
```
pip install mkdocs-minify-plugin
```

Getting help¶

The following links provide further information for various operating systems.

Last update: January 28, 2021