Update documentation for Apple #2117
Conversation
WalkthroughThis pull request updates the documentation for Changes
Possibly related PRs
Poem
Tip New featuresWalkthrough comment now includes:
Notes:
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Outside diff range, codebase verification and nitpick comments (1)
docs/apple-client.md (1)
18-18: Info note modification is appropriate but verify the exclamation usage.The change in the info note to "Instructions on your headscale instance" is suitable as it generalises the information for all Apple devices. However, the use of three exclamation marks might be seen as excessive. Consider reducing it to maintain a professional tone in the documentation.
-!!! info "Instructions on your headscale instance" +! info "Instructions on your headscale instance"
Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Files selected for processing (3)
- README.md (1 hunks)
- docs/apple-client.md (1 hunks)
- mkdocs.yml (1 hunks)
Additional context used
LanguageTool
docs/apple-client.md
[style] ~17-~17: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1035 characters long)
Context: ...7). ### Configuring the headscale URL !!! info "Instructions on your headscale in...(EN_EXCESSIVE_EXCLAMATION)
README.md
[grammar] ~72-~72: The operating system from Apple is written “macOS”.
Context: ... | | macOS | Yes (see docs and/appleon your headscale for mor...(MAC_OS)
Additional comments not posted (4)
docs/apple-client.md (2)
1-1: Header change enhances clarity.The change from "Connecting an iOS client" to "Connecting an Apple client" broadens the scope of the documentation to include both iOS and macOS, aligning with the updated content that addresses both platforms.
10-10: Reorganisation of section headers.The reorganisation from "## iOS" to "### Installation" under the iOS section is a logical restructuring that clarifies the hierarchy of information, making it easier for users to navigate the documentation.
Also applies to: 12-12
mkdocs.yml (1)
142-142: Navigation update aligns with documentation restructuring.The addition of "Apple: apple-client.md" and the removal of "iOS: iOS-client.md" in the navigation structure are consistent with the broader documentation updates that now encompass both macOS and iOS under a unified Apple category. This change simplifies the navigation and reflects the updated documentation focus.
README.md (1)
72-73: Updated documentation links enhance navigability.The modifications to the documentation links for macOS and iOS, which now point to more specific sections within the same documentation file, improve user navigability and access to relevant information. This change is a positive step towards making the documentation more user-friendly and accessible.
Tools
LanguageTool
[grammar] ~72-~72: The operating system from Apple is written “macOS”.
Context: ... | | macOS | Yes (see docs and/appleon your headscale for mor...(MAC_OS)
There was a problem hiding this comment.
Actionable comments posted: 5
Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Files selected for processing (4)
- README.md (1 hunks)
- docs/apple-client.md (1 hunks)
- docs/windows-client.md (1 hunks)
- mkdocs.yml (1 hunks)
Files skipped from review due to trivial changes (1)
- docs/windows-client.md
Files skipped from review as they are similar to previous changes (1)
- mkdocs.yml
Additional context used
LanguageTool
docs/apple-client.md
[style] ~6-~6: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1604 characters long)
Context: ...ilscale.com) clients withheadscale. !!! info "Instructions on your headscale in...(EN_EXCESSIVE_EXCLAMATION)
[uncategorized] ~22-~22: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ... on the iOS device - Scroll down to thethird party appssection, underGame Centeror `...(EN_COMPOUND_ADJECTIVE_INTERNAL)
[grammar] ~34-~34: The operating system from Apple is written “macOS”.
Context: ...of the available [Tailscale clients for MacOS](https://tailscale.com/kb/1065/macos-va...(MAC_OS)
README.md
[grammar] ~72-~72: The operating system from Apple is written “macOS”.
Context: ... | | macOS | Yes (see docs and/appleon your headscale for mor...(MAC_OS)
Markdownlint
docs/apple-client.md
42-42: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
42-42: Expected: indented; Actual: fenced
Code block style(MD046, code-block-style)
* Rename docs/ios-client.md to docs/apple-client.md. Add instructions for macOS; those are copied from the /apple endpoint and slightly modified. Fix doc links in the README. * Move infoboxes for /apple and /windows under the "Goal" section to the top. Those should be seen by users first as they contain *their* specific headscale URL. * Swap order of macOS and iOS to move "Profiles" further down. * Remove apple configuration profiles * Remove Tailscale versions hints * Mention /apple and /windows in the README along with their docs See: juanfont#2096
There was a problem hiding this comment.
Actionable comments posted: 0
Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Files selected for processing (6)
- README.md (1 hunks)
- docs/apple-client.md (1 hunks)
- docs/windows-client.md (1 hunks)
- hscontrol/templates/apple.html (2 hunks)
- integration/scenario_test.go (1 hunks)
- mkdocs.yml (1 hunks)
Files skipped from review due to trivial changes (1)
- integration/scenario_test.go
Files skipped from review as they are similar to previous changes (2)
- docs/windows-client.md
- mkdocs.yml
Additional context used
LanguageTool
docs/apple-client.md
[style] ~6-~6: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1604 characters long)
Context: ...ilscale.com) clients withheadscale. !!! info "Instructions on your headscale in...(EN_EXCESSIVE_EXCLAMATION)
[uncategorized] ~22-~22: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ... on the iOS device - Scroll down to thethird party appssection, underGame Centeror `...(EN_COMPOUND_ADJECTIVE_INTERNAL)
README.md
[grammar] ~72-~72: The operating system from Apple is written “macOS”.
Context: ... | | macOS | Yes (see docs and/appleon your headscale for mor...(MAC_OS)
Markdownlint
docs/apple-client.md
42-42: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
42-42: Expected: indented; Actual: fenced
Code block style(MD046, code-block-style)
Additional comments not posted (6)
docs/apple-client.md (3)
5-11: Clarify the endpoint information.The documentation mentions an endpoint at
/appleon the running instance but does not specify what type of information or interface the user can expect to find there. It would be beneficial to provide a brief description of what the endpoint offers or how it aids in the connection process.Would you like me to draft a more detailed description for this endpoint, or would you prefer to update it yourself?
Tools
LanguageTool
[style] ~6-~6: Using many exclamation marks might seem excessive (in this case: 3 exclamation marks for a text that’s 1604 characters long)
Context: ...ilscale.com) clients withheadscale. !!! info "Instructions on your headscale in...(EN_EXCESSIVE_EXCLAMATION)
22-22: Hyphenate compound adjectives for clarity.The phrase "third party apps" should be hyphenated when used as a compound adjective:
- Scroll down to the `third party apps` section + Scroll down to the `third-party apps` sectionThis change will improve the readability and correctness of the documentation.
Tools
LanguageTool
[uncategorized] ~22-~22: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ... on the iOS device - Scroll down to thethird party appssection, underGame Centeror `...(EN_COMPOUND_ADJECTIVE_INTERNAL)
42-44: Specify the language for code blocks and adjust the code block style.The fenced code block should specify a language for better syntax highlighting and readability. Additionally, the code block style should be consistent with the rest of the documentation:
- ``` + ```bash tailscale login --login-server <YOUR_HEADSCALE_URL>Also, consider using indentation for code blocks instead of fencing if that is the standard in this documentation.
Tools
Markdownlint
42-42: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
42-42: Expected: indented; Actual: fenced
Code block style(MD046, code-block-style)
hscontrol/templates/apple.html (2)
Line range hint
65-129: Review the macOS configuration section for consistency and clarity.The macOS configuration section follows the iOS instructions and has been adjusted for consistency. Verify that the instructions are clear and the formatting is consistent with the rest of the document. The links to download profiles should be checked to ensure they are accessible and correct.
28-62: Review the iOS configuration section for clarity and accuracy.The iOS configuration section has been reorganized and updated to provide clearer instructions. Ensure that the steps are accurate and easy to follow for users. The use of placeholders like
{{.URL}}should be verified to ensure they are correctly replaced during template rendering.README.md (1)
65-73: Update the documentation links for macOS and iOS.The modifications to the "Client OS support" section enhance the clarity and navigability of the documentation. The links provided for macOS and iOS now point to more specific sections, which is a significant improvement. However, ensure that the capitalisation of "macOS" is consistent throughout the document:
- | macOS | Yes (see [docs](./docs/apple-client.md#macos) and `/apple` on your headscale for more information) + | macOS | Yes (see [docs](./docs/apple-client.md#macOS) and `/apple` on your headscale for more information)Tools
LanguageTool
[grammar] ~72-~72: The operating system from Apple is written “macOS”.
Context: ... | | macOS | Yes (see docs and/appleon your headscale for mor...(MAC_OS)
* Rename docs/ios-client.md to docs/apple-client.md. Add instructions for macOS; those are copied from the /apple endpoint and slightly modified. Fix doc links in the README. * Move infoboxes for /apple and /windows under the "Goal" section to the top. Those should be seen by users first as they contain *their* specific headscale URL. * Swap order of macOS and iOS to move "Profiles" further down. * Remove apple configuration profiles * Remove Tailscale versions hints * Mention /apple and /windows in the README along with their docs See: juanfont#2096
I tried hard not to modify the actual instructions as I don't have Apple devices that I could use to test it.
See the commit message for details.
Summary by CodeRabbit