docs build system: Fixed manual to be compatible with mdbook 0.5.x

Maintains compatibility with mdbook 0.4.x.

Includes comments for what to remove once 0.5.x is the only we care
about. Some other changes technically could be changed at that point,
but currently serve to enable universal support of 0.4.x and 0.5.x

Fixes #1051.

Change-Id: Ic5b405038d180bcd357bbd9e5716879e0c26e5f5

doc/manual/anchors.jq

@@ -24,8 +24,8 @@ def map_contents_recursively(transformer):
 def process_command:
     .[0] as $context |
     .[1] as $body |
-    $body + {
-        sections: $body.sections | map(map_contents_recursively(if $context.renderer == "html" then transform_anchors_html else transform_anchors_strip end)),
-    };
+	# XXX FUTURE: drop sections once mdBook is at 0.5.0 or above in nixpkgs
+	$body | (.items? // .sections) |= map(map_contents_recursively(if $context.renderer == "html" then transform_anchors_html else transform_anchors_strip end))
+	;
 
 process_command

doc/manual/book.toml

@@ -22,20 +22,21 @@ fold.level = 30
 # not want to disable the links preprocessor entirely though because that requires
 # disabling *all* built-in preprocessors and selectively reenabling those we want.
 [preprocessor.substitute]
-command = "python3 doc/manual/substitute.py"
+command = "python3 substitute.py"
 before = ["anchors", "links"]
 
 [preprocessor.anchors]
 renderers = ["html"]
-command = "jq --from-file doc/manual/anchors.jq"
+command = "jq --from-file anchors.jq"
 
 [output.markdown]
 
-[output.linkcheck]
+# XXX FUTURE: may be reenabled once mdBook 0.5.0 or above and matching mdbook-linkchecker are in nixpkgs
+#[output.linkcheck]
 # no Internet during the build (in the sandbox)
-follow-web-links = false
+#follow-web-links = false
 
 # mdbook-linkcheck does not understand [foo]{#bar} style links, resulting in
 # excessive "Potential incomplete link" warnings. No other kind of warning was
 # produced at the time of writing.
-warning-policy = "ignore"
+#warning-policy = "ignore"

doc/manual/meson.build

@@ -42,8 +42,9 @@ manual = custom_target(
     '-c',
     '''
         @0@ @INPUT0@ @CURRENT_SOURCE_DIR@ > @DEPFILE@
+        cd @3@
+        @1@ build . -d @2@ | { grep -Fv "because fragment resolution isn't implemented" || :; }
         cd @SOURCE_ROOT@
-        @1@ build doc/manual -d @2@ | { grep -Fv "because fragment resolution isn't implemented" || :; }
         rm -rf @2@/manual
         mv @2@/html @2@/manual
         find @2@/manual -iname meson.build -delete
@@ -51,6 +52,7 @@ manual = custom_target(
       python.full_path(),
       mdbook.full_path(),
       meson.current_build_dir(),
+      meson.current_source_dir()
     ),
   ],
   input : [
@@ -81,7 +83,7 @@ manual = custom_target(
   depfile : 'manual.d',
   env : {
     'RUST_LOG': 'info',
-    'MDBOOK_SUBSTITUTE_SEARCH': meson.current_build_dir() / 'src',
+    'MANUAL_SUBSTITUTE_SEARCH': meson.current_build_dir() / 'src',
   },
 )
 manual_md = manual[1]

doc/manual/substitute.py

@@ -70,9 +70,10 @@ def do_include(content: str, relative_md_path: Path, source_root: Path, search_p
 
 def recursive_replace(data, book_root, search_path):
     match data:
-        case {'sections': sections}:
+        # XXX FUTURE: drop sections once mdBook is at 0.5.0 or above in nixpkgs
+        case {'sections': items} | {'items': items}:
             return data | dict(
-                sections = [recursive_replace(section, book_root, search_path) for section in sections],
+                items = [recursive_replace(item, book_root, search_path) for item in items],
             )
         case {'Chapter': chapter}:
             path_to_chapter = Path(chapter['path'])
@@ -119,10 +120,10 @@ def main():
     context, book = json.load(sys.stdin)
 
     # book_root is the directory where book contents leave (ie, src/)
-    book_root = Path(context['root']) / context['config']['book']['src']
+    book_root = Path(context['root']) / context['config']['book'].get('src', 'src')
 
     # includes pointing into @generated@ will look here
-    search_path = Path(os.environ['MDBOOK_SUBSTITUTE_SEARCH'])
+    search_path = Path(os.environ['MANUAL_SUBSTITUTE_SEARCH'])
 
     # Find @var@ in all parts of our recursive book structure.
     replaced_content = recursive_replace(book, book_root, search_path)

package.nix

@@ -335,7 +335,10 @@ stdenv.mkDerivation (finalAttrs: {
   ]
   ++ [
     (lib.getBin lowdown-unsandboxed)
-    mdbook
+    (lib.warnIf (lib.versionAtLeast mdbook.version "0.5.0")
+      "Workarounds for mdbook 0.4.x/0.5.x interoperability can be removed when 0.5.0 or above is in nixpkgs-stable"
+      mdbook
+    )
     mdbook-linkcheck
   ]
   ++ [