Documentation #1
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds a comprehensive documentation chapter about Devcontainers, explaining their purpose, benefits, and practical usage in development workflows.
- Introduces Chapter 2 covering Devcontainers philosophy and implementation
- Provides practical guidance on when to use (or skip) devcontainers
- Includes concrete configuration examples and tooling recommendations
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
book/src/chapter_2.md |
New chapter providing comprehensive coverage of devcontainers, including rationale, minimal configuration examples, and integration with Nix |
book/src/SUMMARY.md |
Updated table of contents to include the new Devcontainer chapter |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
book/src/nix/home-manager.md
Outdated
| ## Up Next: Just | ||
|
|
||
| You've seen `just rebuild` above. The next chapter covers Just—a command runner that ties these tools together with simple, memorable commands. |
There was a problem hiding this comment.
The documentation references "The next chapter covers Just" but there is no Just chapter in the SUMMARY.md table of contents. Either the Just chapter should be added or this reference should be removed/updated to avoid confusion.
| ## Up Next: Just | |
| You've seen `just rebuild` above. The next chapter covers Just—a command runner that ties these tools together with simple, memorable commands. | |
| ## Just | |
| You've seen `just rebuild` above. Just is a command runner that ties these tools together with simple, memorable commands. |
| buildInputs = with pkgs; [ just cheat asciinema presenterm tmux mdbook ]; | ||
| ``` | ||
|
|
||
| Each of these gets its own chapter later. The point is: adding tools is trivial. One line in `shell.nix`, and everyone who clones this repo gets the same environment. |
There was a problem hiding this comment.
The documentation states "Each of these gets its own chapter later" referring to the tools in shell.nix (just, cheat, asciinema, presenterm, tmux, mdbook), but none of these chapters appear in the SUMMARY.md. This creates an unfulfilled promise to readers. Consider either adding these chapters or removing this forward reference.
| Each of these gets its own chapter later. The point is: adding tools is trivial. One line in `shell.nix`, and everyone who clones this repo gets the same environment. | |
| Whether it's just one tool or many, adding them is trivial. One line in `shell.nix`, and everyone who clones this repo gets the same environment. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 8 out of 9 changed files in this pull request and generated 6 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ## Up Next: Just | ||
|
|
||
| You've seen `just rebuild` above. The [next chapter](./tools/just.md) covers Just—a command runner that ties these tools together with simple, memorable commands. |
There was a problem hiding this comment.
The relative path in this link is incorrect. Since this file is located at book/src/nix/home-manager.md, the path "./tools/just.md" tries to find tools/ inside the nix/ directory. The correct relative path should be "../tools/just.md" to navigate up to the src directory, then into the tools directory.
| You've seen `just rebuild` above. The [next chapter](./tools/just.md) covers Just—a command runner that ties these tools together with simple, memorable commands. | |
| You've seen `just rebuild` above. The [next chapter](../tools/just.md) covers Just—a command runner that ties these tools together with simple, memorable commands. |
|
|
||
| - https://github.com/casey/just | ||
| - https://just.systems/man/en/ | ||
| - https://learnxinyminutes.com/make/ |
There was a problem hiding this comment.
The learnxinyminutes link appears to point to a "make" tutorial page rather than a "just" tutorial page. Since this is documentation for Just (not Make), this link should either point to Just-specific documentation or be removed. If the intention is to contrast Just with Make, consider clarifying this in the link text.
| - https://learnxinyminutes.com/make/ | |
| - [Learn Make in Y Minutes (for comparison)](https://learnxinyminutes.com/make/) |
| Just is a project tool—you need it when working on *this* project, not globally. That's why it's in `shell.nix`: | ||
|
|
||
| ```nix | ||
| buildInputs = with pkgs; [ just cheat asciinema presenterm tmux mdbook ]; |
There was a problem hiding this comment.
Package name inconsistency between code examples. This example shows "asciinema" but the nix/README.md file at line 75 shows "asciinema_3" in the shell.nix example. The documentation should use consistent package names across all examples to avoid confusion.
| buildInputs = with pkgs; [ just cheat asciinema presenterm tmux mdbook ]; | |
| buildInputs = with pkgs; [ just cheat asciinema_3 presenterm tmux mdbook ]; |
| "features": { | ||
| "ghcr.io/devcontainers/features/nix:1": { | ||
| "packages": ["direnv"] | ||
| } |
There was a problem hiding this comment.
There's a potential documentation inconsistency. The chapter shows the initial setup with direnv in the Nix feature packages array, but the current devcontainer.json (line 8) indicates that direnv is now handled by home-manager. This evolution should be explicitly mentioned in the documentation to explain why the initial setup differs from the current state, or the example should be updated to match the current configuration.
| - [Devcontainers](./chapter_2.md) | ||
| - [Nix](./nix/README.md) | ||
| - [Home Manager](./nix/home-manager.md) | ||
| - [Flakes]() |
There was a problem hiding this comment.
The Flakes entry has an empty link target, which will result in a broken link in the generated documentation. Either provide the actual path to the Flakes documentation file, or remove this entry until the documentation is ready.
| - [Flakes]() |
There was a problem hiding this comment.
placeholder to denote flakes are not forgotten but not implemented/documented yet
| ripgrep # Fast search | ||
| jujutsu # Git-compatible VCS | ||
| gh # GitHub CLI | ||
| claude-code # AI assistant |
There was a problem hiding this comment.
The package name "claude-code" may not be a standard Nix package. Claude is typically accessed via API or web interface, not as a standalone installable package. Verify that this package exists in nixpkgs or clarify if this is a custom package. If it doesn't exist, this could cause build failures when users try to apply this configuration.
| claude-code # AI assistant | |
| fd # Fast file finder |
This PR adds a comprehensive documentation chapters about: