Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Restructure headscale documentation #2163

Merged
merged 29 commits into from
Oct 10, 2024
Merged

Restructure headscale documentation #2163

merged 29 commits into from
Oct 10, 2024

Conversation

nblock
Copy link
Collaborator

@nblock nblock commented Oct 2, 2024 •
edited
Loading

Following the spirit of the 0.23 release, this PR aims to restructure the existing documentation to improve
maintanability while providing more information to users. It is mainly a preparation for versioned documentation in the
future which will allow us to evolve the documentation alongside headscale releases. Relevant aspects of this PR:

  • Split the documentation into multiple sections:
    • About: Information about the project: FAQ, features, client compat, contributing, …
    • Setup: Requirements, Install page for varous release, Upgrading
    • Usage: "Getting started", Connecting with Android/Apple/Windows
    • Reference: specific documentation (acl, dns, oidc, …) and integration with other components (reverse proxy, Web UI)
  • Remove duplication and split the common parts into their own pages
  • Document more ways to install headscale (official binaries and packages, distribution, container, …).
  • Add a configuration reference
  • Reuse existing documentation such as CONTRIBUTING.md
  • Replace duplicate content in the README with links to the docs (features, client)
  • Update wording to headscale (in regular text), Headscale (beginning of a sentence) and headscale when referring to the CLI.
  • Add redirects from old links to the new pages

A preview is available here: https://nblock.github.io/headscale/

Fixes: #2164
Ref: #1863

  • have read the CONTRIBUTING.md file
  • raised a GitHub issue or discussed it on the projects chat beforehand
  • added unit tests
  • added integration tests
  • updated documentation if needed
  • updated CHANGELOG.md

@nblock nblock marked this pull request as draft October 2, 2024 12:31
@nblock nblock changed the title Docs Restructure headscale documentation Oct 2, 2024
@nblock nblock marked this pull request as ready for review October 2, 2024 14:24
kradalby
kradalby approved these changes Oct 9, 2024
View reviewed changes
Copy link
Collaborator

@kradalby kradalby left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this looks great, it looks a lot more coherent and a lot more maintainable than our current documentation.
This is extremely helpful!

docs/ref/configuration.md Outdated Show resolved Hide resolved
docs/setup/requirements.md Outdated Show resolved Hide resolved
docs/usage/getting-started.md Outdated Show resolved Hide resolved
nblock added 22 commits October 9, 2024 15:39
@nblock
Setup mkdocs-redirects
8e2aab7
@nblock
Restructure existing documentation
5a432ee
@nblock
Move client OS support into the documentation
5c11224 
* Move existing Client OS support table into its own documentation page
* Link from README.md to the rendered documentation
* Document minimum Tailscale client version
@nblock
Reuse CONTRIBUTING.md" in the documentation
9cdaa36 
* Include "CONTRIBUTING.md" from the repository root
* Update FAQ and index page and link to the contributing docs
@nblock
Add configuration reference
35f8395
@nblock
Add a getting started page and explain the first steps with headscale
40e226c 
* Use the existing "Using headscale" sections and combine them into a
  single getting started guide with a little bit more explanation.
* Explain how to get help from the command line client.
* Remove duplicated sections from existing installation guides
@nblock
Document requirements and assumptions
ba5b944
@nblock
Document packages provided by the community
3f8b73e
@nblock
Move deb install guide to official releases
cbe2483
@nblock
Move manual install guide to official releases
68e9e68
@nblock
Move container documentation to setup section
85641a5
@nblock
Move sealos documentation to cloud install page
5882ca4
@nblock
Move OpenBSD docs to build from source
de48d48
@nblock
Simplify DNS documentation
c153948
@nblock
Add sponsor page
977c740
@nblock
Add releases page
94fb48e
@nblock
Add features page
ff1fc93
@nblock
Add help page
7a65c56
@nblock
Add upgrading page
706ee10
@nblock
Adjust mkdocs nav
6f16d50
@nblock
Update wording
159746f 
Use the term headscale for the project, Headscale on the beginning of a
sentence and `headscale` when refering to the CLI.
@nblock
Welcome to headscale
6cd69d7
kradalby
kradalby reviewed Oct 9, 2024
View reviewed changes
mkdocs.yml Show resolved Hide resolved
@kradalby
Copy link
Collaborator

kradalby commented Oct 9, 2024

I'm very happy with this, I will let the tests run and then roll out tomorrow unless you have any other things you think should be part of it @nblock

@nblock
Copy link
Collaborator Author

nblock commented Oct 9, 2024

I'm very happy with this, I will let the tests run and then roll out tomorrow unless you have any other things you think should be part of it @nblock

I'm happy with it for now.

@kradalby kradalby merged commit 8c7d8ee into juanfont:main Oct 10, 2024
118 of 121 checks passed
@nblock nblock deleted the docs branch October 10, 2024 14:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@kradalby kradalby kradalby approved these changes

@ohdearaugustin ohdearaugustin Awaiting requested review from ohdearaugustin ohdearaugustin is a code owner

@juanfont juanfont Awaiting requested review from juanfont juanfont is a code owner

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

[Bug] Tailscale HEAD (1eaad7d3d) is broken in integration tests
2 participants
@nblock @kradalby