starred/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2026-01-11 20:00:28 +01:00
Code Issues 98 Packages Projects Releases 10 Wiki Activity

[Feature] Improve docu development #718

New Issue
Closed
opened 2025-12-29 02:22:49 +01:00 by adam · 2 comments
adam commented 2025-12-29 02:22:49 +01:00
Owner
Copy Link

Originally created by @ohdearaugustin on GitHub (May 31, 2024).

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

  • I can write the design doc for this feature
  • 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
Originally created by @ohdearaugustin on GitHub (May 31, 2024). ### 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](https://github.com/nix-community/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
adam added the enhancementstale labels 2025-12-29 02:22:49 +01:00
adam closed this issue 2025-12-29 02:22:49 +01:00
adam commented 2025-12-29 02:22:49 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Aug 30, 2024):

This issue is stale because it has been open for 90 days with no activity.

@github-actions[bot] commented on GitHub (Aug 30, 2024): This issue is stale because it has been open for 90 days with no activity.
adam commented 2025-12-29 02:22:49 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Sep 6, 2024):

This issue was closed because it has been inactive for 14 days since being marked as stale.

@github-actions[bot] commented on GitHub (Sep 6, 2024): This issue was closed because it has been inactive for 14 days since being marked as stale.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
CLI
DERP
DNS
Nix
OIDC
SSH
bug
database
documentation
duplicate
enhancement
faq
good first issue
grants
help wanted
might-come
needs design doc
needs investigation
no-stale-bot
out of scope
performance
policy 📝
pull-request
Mirrored from GitHub Pull Request
 question
regression
routes
stale
tags
tailscale-feature-gap
well described ❤️
wontfix
No Label enhancement stale
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/headscale#718
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?