doctester: repl examples

.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+
+[*.rs]
+indent_style = space
+indent_size = 4

.github/workflows/ci.yml

@@ -21,5 +21,7 @@ jobs:
       run: nix-build
     - name: Linkcheck
       run: nix-shell --run "make linkcheck"
+    - name: Run doctests
+      run: nix run .#doctests
     - name: Run code block tests
       run: nix-shell --run "./run_code_block_tests.sh"

README.md

@@ -9,12 +9,22 @@
 
 Official documentation for getting things done with Nix.
 
-## Contributing
+## Development daemon
 
 Run `./live` and open a browser at <http://localhost:5500>.
 
 As you make changes your browser should auto-reload within a few seconds.
 
+## Guidelines
+
 For contents and style see [contribution guide](CONTRIBUTING.md).
 
 For syntax see [RST/Sphinx Cheatsheet](https://sphinx-tutorial.readthedocs.io/cheatsheet/).
+
+## Doctests
+
+Must be run in the repository root.
+
+- Single run: `nix run .#doctests`
+- Daemon: `nix run .#watch-doctests`
+

flake.nix

@@ -49,8 +49,30 @@
             }
           );
         };
+        contentPath = "source";
+        doctester = pkgs.writeShellScriptBin "doctester" ''
+          ${pkgs.lib.getExe eelco} ${pkgs.nix}/bin/nix '${contentPath}/**/*.md'
+        '';
+        doctests-watcher = pkgs.writeShellScriptBin "doctests-watcher" ''
+          ${pkgs.watchexec}/bin/watchexec \
+            --watch=${contentPath}\
+            --restart\
+            --shell=none\
+            --emit-events-to=none\
+            --no-meta\
+            --print-events\
+            '${doctester}/bin/doctester'
+        '';
       in
       rec {
+        apps.doctests = {
+          type = "app";
+          program = "${doctester}/bin/doctester";
+        };
+        apps.watch-doctests = {
+          type = "app";
+          program = "${doctests-watcher}/bin/doctests-watcher";
+        };
         packages = flake-utils.lib.flattenTree {
           nix-dev-pyenv = pkgs.poetry2nix.mkPoetryEnv {
             projectDir = self;

source/_ext/nix_repl_workaround.py

@@ -0,0 +1,13 @@
+from pygments.lexer import RegexLexer
+from pygments.token import Text
+
+class NixReplLexer(RegexLexer):
+    name = 'Nix REPL'
+    aliases = ['nix-repl']
+    filenames = []
+
+    tokens = {
+        'root': [
+            (r'.+', Text),
+        ],
+    }

source/conf.py

@@ -127,6 +127,10 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 
+from nix_repl_workaround import NixReplLexer
+from sphinx.highlighting import lexers
+lexers['nix-repl'] = NixReplLexer()
+
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
 

source/tutorials/first-steps/nix-language.md

@@ -114,7 +114,11 @@ Use [`nix repl`] to evaluate Nix expressions interactively (by typing them on th
 ```shell-session
 $ nix repl
 Welcome to Nix 2.13.3. Type :? for help.
+```
+
+And you have a REPL:
 
+```nix-repl
 nix-repl> 1 + 2
 3
 ```
@@ -127,7 +131,7 @@ If your output does not match the example, try prepending `:p` to the input expr
 
 Example:
 
-```shell-session
+```nix-repl
 nix-repl> { a.b.c = 1; }
 { a = { ... }; }