We're using several tools for building Kura User Documentation:
- mkdocs: the main tool to generate the static website
- mkdocs-material: the used material-style theme
- mike: the versioning tool, based on mkdocs
In order to install mkdocs, you need to have Python >= 3.8 and pip installed.
The required dependencies for building the documentation can be found in the root folder requirement.txt file. For installing them we suggest using a Python Virtual Environment.
Create a virtual environment as follows:
python3 -m venv .venvthis will create a folder in you current path named .venv. Activate the virtual environment with:
source .venv/bin/activateyou're now using the virtual environment, update pip and install the required dependencies.
pip3 install --upgrade pippip3 install -r requirements.txtYou're now ready do build the documentation sources locally.
MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the mkdocs.yml configuration file and you have activated the Python virtual environment, then start the ser
8000
ver by running:
mkdocs serveOpen up http://127.0.0.1:8000/ in your browser, and you'll see the docs built from your current sources.
The MkDocs dev-server also supports auto-reloading, and will rebuild your documentation whenever anything in the configuration file, documentation directory, or theme directory changes.
mike is the tool to use for building and versioning the documentation. Modify the markdown files and edit mkdocs.yml file accordingly.
To build the documentation and see the changes on your local machine:
mike deploy [version]Usually [version] should match the branch you're on. Let's say you're updating the documentation for docs-develop you'll the need to run mike deploy docs-develop. This command will create a folder in you current path names site, here you'll find the built documentation sources. You can serve them through a local webserver using:
mike serveNote: If you can't see your docs it might be because you haven't set a default version to serve. Run the following command for setting the default version to be served by
mike:mike set-default [version]where
[version]is the one you used in thedeploycommand before.
3. A VSCode web instance will be opened in a new tab. Once launched the necessary dependencies will be downloaded, the docs will be compiled, and finally, the docs will be accessible via port 8000.
To access the compiled documentation press the Open in Browser button in the popup.
Or go to the Ports tab and press the Open in Browser icon corresponding to the mkdocs process