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.

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

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
Contributor

@nblock nblock commented Oct 2, 2024

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
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
* Move existing Client OS support table into its own documentation page
* Link from README.md to the rendered documentation
* Document minimum Tailscale client version
* Include "CONTRIBUTING.md" from the repository root
* Update FAQ and index page and link to the contributing docs
* 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
Use the term headscale for the project, Headscale on the beginning of a
sentence and `headscale` when refering to the CLI.
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
Contributor 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
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

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