[Feature] Improve docu development

[ohdearaugustin]

Use case

Easier and streamlined working on documentation locally, improvement of the github action.

Description

Currently we build the documentation with pure python and a requirement.txt file. To get mkdocs running you would have to manually install a virtual env, install dependencies etc. until you get a local version of mkdocs running. This is a bit annoying, because we don't have a specific python version set to get it running and it could cause problem with incomparability. For example some build it with python 3.6 and someone else with 3.12, it could happen that different outcomes are produced.

Furthermore the buildpipeline also doesn't use a specific version of python and it will always run, even when we don't have changes on the documentation.

Contribution

• [X] I can write the design doc for this feature
• [X] I can contribute this feature

How can it be implemented?

The implementation I choose was poetry, as I want it still to be possible for people without nix to easily work on the documentation and be able to see the result locally with just needing poetry. Furthermore my skill about nix aren't that great. Maybe in the future we can migrate to poetry2nix This will need configuration to build headscale and the documentation with nix and I couldn't find a easy way yet to get that done.

The implementation is mainly split into two parts:

1. Local development
2. Github Actions

ad 1)

• Add poetry config to the repo root
• Add python311 and poetry to the nix develop shell
• Add build command to the makefile

ad 2)

• Change github actions to build within the nix shell
• Add caching
• Reduce unneeded action runs

I'm planning on implementing this in 2 steps.

1. Implementation of the above steps
2. Adding documentation on working with the documentation