Merge pull request #1365 from cachix/work/keys/doc-improvement

feat: Documentation improvements

.github/workflows/generate.yml

@@ -31,10 +31,19 @@ jobs:
         add: docs/reference/options.md
         message: 'Auto generate docs/reference/options.md'
 
+    - name: Verify individual docs
+      run: devenv shell devenv-verify-individual-docs
+    - uses: EndBug/add-and-commit@v9
+      if: ${{ github.event_name == 'push' }}
+      with:
+        default_author: github_actions
+        message: 'Auto generate missing individual markdowns'
+
     - name: Generate docs and supported-languages example
       run: |
         devenv shell devenv-generate-docs
         devenv shell devenv-generate-languages-example
+        devenv shell devenv-generate-individual-docs
     - uses: EndBug/add-and-commit@v9
       if: ${{ github.event_name == 'push' }}
       with:
@@ -50,3 +59,4 @@ jobs:
         default_author: github_actions
         add: docs/devenv.schema.json
         message: 'Auto generate docs/devenv.schema.json'
+

devenv.nix

@@ -106,7 +106,7 @@
       set -e
       output_file=docs/reference/options.md
       options=$(nix build --accept-flake-config --no-pure-eval --extra-experimental-features 'flakes nix-command' --show-trace --print-out-paths --no-link '.#devenv-docs-options')
-      echo "# devenv.nix options" > $output_file
+      echo "# devenv.nix" > $output_file
       echo >> $output_file
       cat $options >> $output_file
       # https://github.com/NixOS/nixpkgs/issues/224661
@@ -142,6 +142,71 @@
       EOF
     '';
   };
+  scripts."devenv-generate-individual-docs" = {
+    description = "Generate individual docs of all devenv modules";
+    exec = ''
+      mkdir -p docs/{autogen-language-docs,autogen-service-docs,autogen-process-manager-docs}
+
+      nix build --impure --extra-experimental-features 'flakes nix-command' --show-trace --print-out-paths '.#devenv-generate-individual-docs'
+      cp -r --no-preserve=all result/docs/individual-docs/* docs/
+    '';
+  };
+
+  scripts."devenv-verify-individual-docs" = {
+    description = "Generate missing template markdown files";
+    exec = ''
+
+    process_directory() {
+      local nix_dir=$1
+      local md_dir=$2
+      local category=$3
+
+      nixFiles=($(ls $nix_dir/*.nix))
+      mdFiles=($(ls $md_dir/*.md))
+
+      declare -a nixList
+      declare -a mdList
+
+      # Remove extensions and populate lists
+      for file in "''${nixFiles[@]}"; do
+        baseName=$(basename "$file" .nix)
+        nixList+=("$baseName")
+      done
+
+      for file in "''${mdFiles[@]}"; do
+        baseName=$(basename "$file" .md)
+        mdList+=("$baseName")
+      done
+
+      IFS=$'\n' sorted_nix=($(sort <<<"''${nixList[*]}"))
+      IFS=$'\n' sorted_md=($(sort <<<"''${mdList[*]}"))
+
+      # Compare and create missing files
+      missing_files=()
+      for item in "''${sorted_nix[@]}"; do
+        if [[ ! " ''${sorted_md[@]} " =~ " $item " ]]; then
+          missing_files+=("$item")
+          cat << EOF > "$md_dir/$item.md"
+
+
+[comment]: # (Please add your documentation on top of this line)
+
+@AUTOGEN_OPTIONS@
+EOF
+          echo "Created missing file: $md_dir/$item.md"
+        fi
+      done
+
+      if [ ''${#missing_files[@]} -eq 0 ]; then
+        echo "All $category docs markdown files are present."
+      fi
+    }
+
+    process_directory "src/modules/languages" "docs/individual-docs/languages" "language"
+    process_directory "src/modules/services" "docs/individual-docs/services" "service"
+    process_directory "src/modules/process-managers" "docs/individual-docs/process-managers" "process manager"
+    '';
+  };
 
   pre-commit.hooks = {
     nixpkgs-fmt.enable = true;

docs/.pages

@@ -0,0 +1,47 @@
+nav:
+  - Home: index.md
+  - Documentation:
+    - Getting Started: getting-started.md
+    - Files And Variables: files-and-variables.md
+    - Writing devenv.nix:
+      - Basics: basics.md
+      - Packages: packages.md
+      - Scripts: scripts.md
+      - Languages: 
+        - Overview: languages.md
+        - Supported Languages: autogen-language-docs
+      - Processes: 
+        - Overview: processes.md
+        - Supported Process Managers: autogen-process-manager-docs
+      - Services: 
+        - Overview: services.md
+        - Supported Services: autogen-service-docs
+      - Containers: containers.md
+      - Binary Caching: binary-caching.md
+      - Pre-Commit Hooks: pre-commit-hooks.md
+      - Tests: tests.md
+      - Common Patterns: common-patterns.md
+    - Writing devenv.yaml:
+      - Inputs: inputs.md
+      - Imports: composing-using-imports.md
+    - Overview:
+      - Automatic Shell Activation: automatic-shell-activation.md
+      - Garbage Collection: garbage-collection.md
+    - Guides:
+      - Using With Flakes: guides/using-with-flakes
+      - Using With flake.parts: guides/using-with-flake-parts
+    - Integrations:
+      - .env: integrations/dotenv
+      - GitHub Actions: integrations/github-actions
+      - Codespaces / devcontainer: integrations/codespaces-devcontainer
+      - Difftastic: integrations/difftastic
+      - Android: integrations/android
+    - Examples: examples
+    - Editor Support:
+      - VSCode: editor-support/vscode
+      - PhpStorm: editor-support/phpstorm
+      - Zed: editor-support/zed
+    - Roadmap: roadmap.md
+  - Reference: reference
+  - Blog: blog
+  - Community: community

docs/autogen-language-docs/ansible.md

@@ -0,0 +1,41 @@
+[comment]: # (Do not edit this file as it is autogenerated. Go to docs/individual-docs if you want to make edits.)
+
+
+[comment]: # (Please add your documentation on top of this line)
+
+## languages\.ansible\.enable
+
+Whether to enable tools for Ansible development\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` false `
+
+
+
+*Example:*
+` true `
+
+
+
+## languages\.ansible\.package
+
+
+
+The Ansible package to use\.
+
+
+
+*Type:*
+package
+
+
+
+*Default:*
+` pkgs.ansible `

docs/autogen-language-docs/c.md

@@ -0,0 +1,42 @@
+[comment]: # (Do not edit this file as it is autogenerated. Go to docs/individual-docs if you want to make edits.)
+
+
+[comment]: # (Please add your documentation on top of this line)
+
+## languages\.c\.enable
+
+
+
+Whether to enable tools for C development\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` false `
+
+
+
+*Example:*
+` true `
+
+
+
+## languages\.c\.debugger
+
+An optional debugger package to use with c\.
+The default is ` gdb `, if supported on the current system\.
+
+
+
+*Type:*
+null or package
+
+
+
+*Default:*
+` pkgs.gdb `

docs/autogen-language-docs/clojure.md

@@ -0,0 +1,23 @@
+[comment]: # (Do not edit this file as it is autogenerated. Go to docs/individual-docs if you want to make edits.)
+
+
+[comment]: # (Please add your documentation on top of this line)
+
+## languages\.clojure\.enable
+
+Whether to enable tools for Clojure development\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` false `
+
+
+
+*Example:*
+` true `

docs/autogen-language-docs/cplusplus.md

@@ -0,0 +1,23 @@
+[comment]: # (Do not edit this file as it is autogenerated. Go to docs/individual-docs if you want to make edits.)
+
+
+[comment]: # (Please add your documentation on top of this line)
+
+## languages\.cplusplus\.enable
+
+Whether to enable tools for C++ development\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` false `
+
+
+
+*Example:*
+` true `

docs/autogen-language-docs/crystal.md

@@ -0,0 +1,23 @@
+[comment]: # (Do not edit this file as it is autogenerated. Go to docs/individual-docs if you want to make edits.)
+
+
+[comment]: # (Please add your documentation on top of this line)
+
+## languages\.crystal\.enable
+
+Whether to enable Enable tools for Crystal development…
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` false `
+
+
+
+*Example:*
+` true `

docs/autogen-language-docs/cue.md

@@ -0,0 +1,41 @@
+[comment]: # (Do not edit this file as it is autogenerated. Go to docs/individual-docs if you want to make edits.)
+
+
+[comment]: # (Please add your documentation on top of this line)
+
+## languages\.cue\.enable
+
+Whether to enable tools for Cue development\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` false `
+
+
+
+*Example:*
+` true `
+
+
+
+## languages\.cue\.package
+
+
+
+The CUE package to use\.
+
+
+
+*Type:*
+package
+
+
+
+*Default:*
+` pkgs.cue `

docs/autogen-language-docs/dart.md

@@ -0,0 +1,41 @@
+[comment]: # (Do not edit this file as it is autogenerated. Go to docs/individual-docs if you want to make edits.)
+
+
+[comment]: # (Please add your documentation on top of this line)
+
+## languages\.dart\.enable
+
+Whether to enable tools for Dart development\.
+
+
+
+*Type:*
+boolean
+
+
+
+*Default:*
+` false `
+
+
+
+*Example:*
+` true `
+
+
+
+## languages\.dart\.package
+
+
+
+The Dart package to use\.
+
+
+
+*Type:*
+package
+
+
+
+*Default:*
+` pkgs.dart `