Feature/docs

.github/workflows/command-block.yml

@@ -1,12 +1,16 @@
 name: Comment on manual command changes
 on:
-  pull_request:
+  pull_request_target:
     paths:
       - 'commands/docs/**'
+      - 'commands/categories/**'
 
 jobs:
   comment:
     runs-on: ubuntu-latest
+    # Maintainers/Contributors can add themselves exempt from this bot if they regularly run the command doc generation.
+    # If you are on this list, be careful about accidental changes!
+    if: ${{!contains(fromJSON('["hustcer", "sholderbach"]'), github.event.pull_request.user.login)}}
     steps:
       - uses: actions/github-script@v7.0.1
         with:
@@ -16,8 +20,13 @@ jobs:
               owner: context.repo.owner,
               repo: context.repo.repo,
               body: 'Awesome that you are trying to improve the documentation of a nushell command!\n\n' +
-                'As we autogenerate these command pages from the help information defined with the command after each release:\n'+
-                '- If you already updated the command help, you are already done!\n'+
-                '- Else, please look for the command in the [source tree](https://github.com/nushell/nushell/tree/main/crates) and make your changes directly there.\n\n'+
+                '**You should not modify the files in `commands/docs` or `commands/categories`!**\n' +
+                'We autogenerate these command pages from the `help` information defined by the command implementation, after each release. Thus:\n'+
+                '- If you already updated the command help, you are already done and can close this PR!\n'+
+                '- Else, please look for the command in the [source tree](https://github.com/nushell/nushell/tree/main/crates) and make your changes directly there in the `impl Command` and `Signature`.\n'+
+                '- If you accidentally made a change in `commands/` while working on general documentation, please revert changes to `commands/`\n\n'+
                 'Thanks for helping out!'
             })
+      - run: |
+          echo "This PR touched autogenerated command docs. If you are not a maintainer of the autogenerated docs, please revert changes to `commands/docs/**` and make the change on the nushell side"
+          exit 1

.vuepress/configs/sidebar/command_categories.ts

@@ -10,6 +10,7 @@ export const commandCategories = [
   '/commands/categories/date.md',
   '/commands/categories/debug.md',
   '/commands/categories/default.md',
+  '/commands/categories/deprecated.md',
   '/commands/categories/env.md',
   '/commands/categories/expression.md',
   '/commands/categories/filesystem.md',

blog/2024-12-04-configuration_preview.md

@@ -14,7 +14,7 @@ Today, we're releasing two documentation items related to these changes:
 
 - A guide to upgrading your configuration to take advantage of the enhancements (below). This will also be linked from the 0.101 Release Notes when it becomes available.
 
-- A [preview of the new Configuration chapter](/book/configuration_preview.md) of the Book. This chapter has been rewritten to match the new functionality, as well as add some previously missing documentation on features like autoload dirs (and more). Once 0.101 releases, this will replace the previous configuration chapter. We welcome reviews of the updates, and any corrections or enhancements can be submitted to [the doc repository](https://github.com/nushell/nushell.github.io) if needed.
+- A [<s>preview of the</s> (now live) new Configuration chapter](/book/configuration) of the Book. This chapter has been rewritten to match the new functionality, as well as add some previously missing documentation on features like autoload dirs (and more). Once 0.101 releases, this will replace the previous configuration chapter. We welcome reviews of the updates, and any corrections or enhancements can be submitted to [the doc repository](https://github.com/nushell/nushell.github.io) if needed.
 
 ---
 
@@ -126,8 +126,7 @@ $env.config.history = {
 - The commented, sample `default_env.nu` and `default_config.nu` in older releases was useful for learning about configuration options. Since these (long) files are no longer copied to the filesystem, you can access an enhanced version of this documentation using:
 
   ```nu
-  config env --sample | nu-highlight | less -R
-  config nu --sample | nu-highlight | less -R
+  config nu --doc | nu-highlight | less -R
   ```
 
 - Skeleton config files (`env.nu` and `config.nu`) are automatically created when the default config directory is created. Usually this will be the first time Nushell is started. The user will no longer be asked whether or not to create the files.
@@ -136,8 +135,6 @@ $env.config.history = {
 
 - An internal `default_env.nu` is loaded immediately before the user's `env.nu`. You can inspect its contents using `config env --default | nu-highlight | less -R`.
 
-  This means that, as with `config.nu`, you can also use your `env.nu` to just override the default environment variables if desired.
-
 - Likewise, a `default_config.nu` is loaded immediately before the user's `config.nu`. View
   this file using `config nu --default | nu-highlight | less -R`.