ControlPage-Docs

Canonical source

I do development on my personal GitLab instance.

But contributions are welcome on Gitlab.com.

Furthermore, this project is mirrored to GitHub. But don't open any issues or pull requests there!

Installation

Install dependencies for doc.

1. Creating a virtual environment

   As with any python project it is usually recommended creating a virtual environment:

   python -m venv env
   # enter / re-enter later the venv using:
   source env/bin/activate

2. Install dependencies using provided requirements file

   pip install -r requirements.txt

Local Development

# run using the provided helper script
npm start
# or directly using
mkdocs serve

Building

mkdocs build

This generates a static site into the site directory that can be served by any web server / static web hosting provider like GitHub Pages / GitLab Pages / ....

To check out the result you could also for example use pythons built-in web server by running python3 -m http.server 4200 inside the site folder.

Linting

This project uses markdownlint for linting.

It can be run either directly from the CLI using npm run lint (after installing the dependency using npm install) or integrated with your editor, see: Related. Furthermore, linting is automatically checked using CI on each PR / for each push.

Some rules have been disabled:

#	Rule	Why
MD013	Line length	-
MD033	Inline HTML	Required when using Images.
MD046	Code block style	Interferes with Admonitions.