docs: commit docs in CI and make doc generation idempotent

.github/workflows/generate.yml

@@ -1,13 +1,15 @@
 name: "Generate docs/examples"
+
 on:
  push:
  branches:
  - main
  tags:
  - v*
  pull_request:
+
 jobs:
- build:
+ generate-docs:
  runs-on: ubuntu-latest
  steps:
  - uses: actions/checkout@v4
@@ -19,25 +21,32 @@ jobs:
  with:
  name: devenv
  - run: nix profile install .
+
  - name: Generate doc options
  run: devenv shell devenv-generate-doc-options
- # https://github.com/NixOS/nixpkgs/issues/224661
- - run: sed -i 's/\\\././g' docs/reference/options.md
  - uses: EndBug/add-and-commit@v9
  if: ${{ github.event_name == 'push' }}
  with:
  default_author: github_actions
  add: docs/reference/options.md
  message: 'Auto generate docs/reference/options.md'
- - name: Generate supported-languages example
- run: devenv shell devenv-generate-languages-example
- - name: Generate docs
- run: devenv shell devenv-generate-docs
+
+ - name: Generate docs and supported-languages example
+ run: |
+ devenv shell devenv-generate-docs
+ devenv shell devenv-generate-languages-example
+ - uses: EndBug/add-and-commit@v9
+ if: ${{ github.event_name == 'push' }}
+ with:
+ default_author: github_actions
+ add: docs examples/supported-languages/devenv.nix
+ message: 'Auto generate docs and examples'
+
  - name: Generate JSON schema
  run: devenv generate-json-schema
  - uses: EndBug/add-and-commit@v9
  if: ${{ github.event_name == 'push' }}
  with:
  default_author: github_actions
- add: examples/supported-languages/devenv.nix
- message: 'Auto generate examples/supported-languages/devenv.nix'
+ add: docs/devenv.schema.json
+ message: 'Auto generate docs/devenv.schema.json'

devenv.nix

@@ -96,10 +96,13 @@
  '';
  scripts."devenv-generate-doc-options".exec = ''
  set -e
+ output_file=docs/reference/options.md
  options=$(nix build --impure --extra-experimental-features 'flakes nix-command' --show-trace --print-out-paths --no-link '.#devenv-docs-options')
- echo "# devenv.nix options" > docs/reference/options.md
- echo >> docs/reference/options.md
- cat $options >> docs/reference/options.md
+ echo "# devenv.nix options" > $output_file
+ echo >> $output_file
+ cat $options >> $output_file
+ # https://github.com/NixOS/nixpkgs/issues/224661
+ sed -i 's/\\\././g' $output_file
  '';
  scripts."devenv-generate-languages-example".exec = ''
  cat > examples/supported-languages/devenv.nix <<EOF

src/modules/integrations/hostctl.nix

@@ -20,6 +20,7 @@ in
  hostsProfileName = lib.mkOption {
  type = lib.types.str;
  default = "devenv-${builtins.hashString "sha256" config.env.DEVENV_ROOT}";
+ defaultText = "devenv-<hash>";
  description = "Profile name to use.";
  };
 

src/modules/languages/php.nix

@@ -74,7 +74,7 @@ let
 
  This option is read-only and managed by NixOS.
  '';
- example = "${runtimeDir}/<name>.sock";
+ example = literalExpression ''config.env.DEVENV_STATE + "/php-fpm/<name>.sock"'';
  };
 
  listen = mkOption {
@@ -236,16 +236,21 @@ in
  default = {
  error_log = config.env.DEVENV_STATE + "/php-fpm/php-fpm.log";
  };
+ defaultText = literalExpression ''
+ {
+ error_log = config.env.DEVENV_STATE + "/php-fpm/php-fpm.log";
+ }
+ '';
  description = ''
  PHP-FPM global directives. 
- 
+
  Refer to the "List of global php-fpm.conf directives" section of
  <https://www.php.net/manual/en/install.fpm.configuration.php>
  for details. 
- 
+
  Note that settings names must be enclosed in
  quotes (e.g. `"pm.max_children"` instead of `pm.max_children`). 
- 
+
  You need not specify the options `error_log` or `daemonize` here, since
  they are already set.
  '';

src/modules/languages/python.nix

@@ -171,6 +171,9 @@ in
  libraries = lib.mkOption {
  type = lib.types.listOf lib.types.path;
  default = [ "${config.devenv.dotfile}/profile" ];
+ defaultText = lib.literalExpression ''
+ [ "''${config.devenv.dotfile}/profile" ]
+ '';
  description = ''
  Additional libraries to make available to the Python interpreter.
 

src/modules/languages/rust.nix

@@ -55,7 +55,13 @@ in
  mold.enable = lib.mkOption {
  type = lib.types.bool;
  default = pkgs.stdenv.isLinux && pkgs.stdenv.isx86_64 && cfg.targets == [ ];
- description = "Enable mold as the linker.";
+ defaultText =
+ lib.literalExpression "pkgs.stdenv.isLinux && pkgs.stdenv.isx86_64 && languages.rust.targets == [ ]";
+ description = ''
+ Enable mold as the linker.
+
+ Enabled by default on x86_64 Linux machines when no cross-compilation targets are specified.
+ '';
  };
 
  toolchain = lib.mkOption {

src/modules/processes.nix

@@ -68,6 +68,13 @@ in
  unix-socket = "${config.devenv.runtime}/pc.sock";
  tui = true;
  };
+ defaultText = lib.literalExpression ''
+ {
+ version = "0.5";
+ unix-socket = "''${config.devenv.runtime}/pc.sock";
+ tui = true;
+ }
+ '';
  example = {
  version = "0.5";
  log_location = "/path/to/combined/output/logfile.log";

src/modules/services/caddy.nix

@@ -158,6 +158,7 @@ in
 
  dataDir = mkOption {
  default = "${config.env.DEVENV_STATE}/caddy";
+ defaultText = literalExpression ''"${config.env.DEVENV_STATE}/caddy"'';
  type = types.path;
  description = ''
  The data directory, for storing certificates. Before 17.09, this

src/modules/services/couchdb.nix

@@ -1,25 +1,26 @@
 { pkgs
 , lib
 , config
+, options
 , ...
 }:
 let
  cfg = config.services.couchdb;
+ opts = options.services.couchdb;
 
  settingsFormat = pkgs.formats.ini { };
  configFile = settingsFormat.generate "couchdb.ini" cfg.settings;
 
- baseDir = config.env.DEVENV_STATE + "/couchdb";
  startScript = pkgs.writeShellScriptBin "start-couchdb" ''
  set -euo pipefail
- mkdir -p '${baseDir}'
- touch '${baseDir}/couchdb.uri'
- touch '${baseDir}/couchdb.ini'
+ mkdir -p '${cfg.baseDir}'
+ touch '${cfg.baseDir}/couchdb.uri'
+ touch '${cfg.baseDir}/couchdb.ini'
 
- if [[ ! -e '${baseDir}/.erlang.cookie' ]]; then
- touch '${baseDir}/.erlang.cookie'
- chmod 600 '${baseDir}/.erlang.cookie'
- dd if=/dev/random bs=16 count=1 status=none | base64 > ${baseDir}/.erlang.cookie
+ if [[ ! -e '${cfg.baseDir}/.erlang.cookie' ]]; then
+ touch '${cfg.baseDir}/.erlang.cookie'
+ chmod 600 '${cfg.baseDir}/.erlang.cookie'
+ dd if=/dev/random bs=16 count=1 status=none | base64 > ${cfg.baseDir}/.erlang.cookie
  fi
 
  exec ${cfg.package}/bin/couchdb
@@ -36,12 +37,23 @@ in
  defaultText = lib.literalExpression "pkgs.couchdb3";
  };
 
+ baseDir = lib.mkOption {
+ type = lib.types.str;
+ default = config.env.DEVENV_STATE + "/couchdb";
+ defaultText = lib.literalExpression ''config.env.DEVENV_STATE + "/couchdb"'';
+ readOnly = true;
+ description = ''
+ The directory where CouchDB will store its data.
+ '';
+ };
+
  settings = lib.mkOption {
  type = lib.types.submodule {
  freeformType = settingsFormat.type;
  options.couchdb.database_dir = lib.mkOption {
  type = lib.types.path;
- default = baseDir;
+ default = cfg.baseDir;
+ defaultText = opts.baseDir.defaultText;
  description = ''
  Specifies location of CouchDB database files (*.couch named). This
  location should be writable and readable for the user the CouchDB
@@ -59,7 +71,8 @@ in
  };
  options.couchdb.view_index_dir = lib.mkOption {
  type = lib.types.path;
- default = baseDir;
+ default = cfg.baseDir;
+ defaultText = opts.baseDir.defaultText;
  description = ''
  Specifies location of CouchDB view index files. This location should
  be writable and readable for the user that runs the CouchDB service
@@ -68,7 +81,8 @@ in
  };
  options.couchdb.uri_file = lib.mkOption {
  type = lib.types.path;
- default = "${baseDir}/couchdb.uri";
+ default = "${cfg.baseDir}/couchdb.uri";
+ defaultText = lib.literalExpression (opts.baseDir.defaultText.text + "/couchdb.uri");
  description = ''
  This file contains the full URI that can be used to access this
  instance of CouchDB. It is used to help discover the port CouchDB is
@@ -108,7 +122,7 @@ in
  database_dir = baseDir;
  single_node = true;
  view_index_dir = baseDir;
- uri_file = "${baseDir}/couchdb.uri";
+ uri_file = "''${config.services.couchdb.baseDir}/couchdb.uri";
  };
  admins = {
  "admin_username" = "pass";
@@ -126,10 +140,10 @@ in
  packages = [ cfg.package ];
  services.couchdb.settings = {
  couchdb = {
- database_dir = baseDir;
+ database_dir = cfg.baseDir;
  single_node = true;
- view_index_dir = baseDir;
- uri_file = "${baseDir}/couchdb.uri";
+ view_index_dir = cfg.baseDir;
+ uri_file = "${cfg.baseDir}/couchdb.uri";
  };
  admins = {
  admin = "admin";
@@ -139,7 +153,7 @@ in
  port = 5984;
  };
  };
- env.ERL_FLAGS = "-couch_ini ${cfg.package}/etc/default.ini ${configFile} '${baseDir}/couchdb.ini'";
+ env.ERL_FLAGS = "-couch_ini ${cfg.package}/etc/default.ini ${configFile} '${cfg.baseDir}/couchdb.ini'";
  processes.couchdb.exec = "${startScript}/bin/start-couchdb";
  };
 }