New `devmode` hides build errors

[asymmetric]

Observations
When running nix-shell --run devmode, build errors are kinda hidden (scroll right on the paste below to see: Could not lex literal_block as "nix")

❯ nix-shell --run devmode
Doing an initial build of the docs...
b'warning: Git tree \'/home/asymmetric/code/nix.dev\' is dirty\nwarning: AWS error uploading \'nix-cache-info\': Access Denied\nthis derivation will be built:\n  /nix/store/7zr03l5dp0bawwr2vj4wy200wf9y1mi3-nix-dev.drv\nbuilding \'/nix/store/7zr03l5dp0bawwr2vj4wy200wf9y1mi3-nix-dev.drv\'...\nerror: builder for \'/nix/store/7zr03l5dp0bawwr2vj4wy200wf9y1mi3-nix-dev.drv\' failed with exit code 2;\n       last 25 log lines:\n       > patching sources\n       > configuring\n       > no configure script, doing nothing\n       > building\n       > sphinx-build -b html -d build/doctrees  -W source build/html\n       > Running Sphinx v5.3.0\n       > making output directory... done\n       > myst v1.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={\'colon_fence\', \'linkify\', \'tasklist\'}, disable_syntax=[], all_links_external=False, url_schemes=(\'http\', \'https\', \'mailto\', \'ftp\'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[\'nix\', \'python\'], title_to_header=False, heading_anchors=3, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes=\'tex2jax_process|mathjax_process|math|output_area\', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)\n       > building [mo]: targets for 0 po files that are out of date\n       > building [html]: targets for 45 source files that are out of date\n       > updating environment: [new config] 45 added, 0 changed, 0 removed\n       > /build/source/source/recipes/python-environment.md.md:8: Extracting code block into extracted/python-environment/myapp.py\n       > /build/source/source/recipes/python-environment.md.md:33: Extracting code block into extracted/python-environment/shell.nix\n       > /build/source/source/tutorials/cross-compilation.md.md:270: Extracting code block into extracted/cross-compilation/hello.c\n       > reading sources... [100%] tutorials/nixos/nixos-configuration-on-vmchines00m\n       > looking for now-outdated files... none found\n       > pickling environment... done\n       > checking consistency... done\n       > preparing documents... done\n       > writing output... [100%] tutorials/nixos/nixos-configuration-on-vmchines00m\n       > sphinx-sitemap: sitemap.xml was generated for URL https://nix.dev/ in /build/source/build/html/sitemap.xml\n       >\n       > Warning, treated as error:\n       > /build/source/source/tutorials/module-system/module-system.md:206:Could not lex literal_block as "nix". Highlighting skipped.\n       > make: *** [Makefile:53: html] Error 2\n       For full logs, run \'nix log /nix/store/7zr03l5dp0bawwr2vj4wy200wf9y1mi3-nix-dev.drv\'.\n'
[I 231103 11:32:38 server:335] Serving on http://127.0.0.1:5500
[I 231103 11:32:38 handlers:62] Start watching changes
[I 231103 11:32:38 handlers:64] Start detecting changes

Also notice that the script continues, even though (initial) building failed.

To reproduce

Change the language in a fenced code block on any CommonMark file, thereby inducing a parsing error in sphinx.

Problem
The problem is that nix build is run inside a python script that doesn't (or can't?) do error handling.

Approaches

One way is to make the first build into a dependency of the script. This way, at least initial build errors will be blocking and shown properly. Subsequent ones won't.

diff --git a/flake.nix b/flake.nix
index ee5561b..174b8a0 100644
--- a/flake.nix
+++ b/flake.nix
@@ -27,9 +27,6 @@
 
               build_docs = shell("nix build")
 
-              print("Doing an initial build of the docs...")
-              build_docs()
-
               server.watch("source/*", build_docs)
               server.watch("source/**/*", build_docs)
               server.watch("_templates/*.html", build_docs)
@@ -38,7 +35,7 @@
           in
           pkgs.writeShellApplication {
             name = "devmode";
-            runtimeInputs = [ pythonEnvironment ];
+            runtimeInputs = [ self.packages.${system}.default pythonEnvironment ];
             text = ''
               python ${pkgs.writeText "live.py" script}
             '';

Willing to help?
Claro.

Priorities

Add 👍 to issues you find important.

[asymmetric]

cc @alejandrosame @fricklerhandwerk since you worked on this in 42add65.

[asymmetric]

I also tried seeing if the call to shell could be made to distinguish between errors and success, but I couldn't find a way to distinguish between normal output/warnings and errors (this might be because the nix command prints stuff to stderr when it shouldn't, not sure).

[asymmetric]

Also, IME it's quite a bit slower than the previous version, probably because it goes through a whole nix build rather than just calling sphinx-bulid.

[alejandrosame]

@asymmetric Please try PR #788. The error now gets rendered and displayed in the browser.

At the moment we introduced this devmode I wanted to reuse somehow the manuals utility, since there was a considerable effort to make it work resiliently. This problem probably justifies the copy-pasting in the PR until the utility is accessible from outside of nixpkgs.

[asymmetric]

This was fixed in #811