meson: Generate documentation

.gitignore

@@ -12,18 +12,6 @@ perl/Makefile.config
 /svn-revision
 /libtool
 
-# /doc/manual/
-/doc/manual/*.1
-/doc/manual/*.5
-/doc/manual/*.8
-/doc/manual/nix.json
-/doc/manual/conf-file.json
-/doc/manual/builtins.json
-/doc/manual/src/SUMMARY.md
-/doc/manual/src/command-ref/new-cli
-/doc/manual/src/command-ref/conf-file.md
-/doc/manual/src/expressions/builtins.md
-
 # /scripts/
 /scripts/nix-profile.sh
 /scripts/nix-reduce-build

doc/manual/local.mk

@@ -86,6 +86,5 @@ install: $(d)/src/command-ref/new-cli
 
 $(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/command-ref/conf-file.md $(d)/src/expressions/builtins.md
 	$(trace-gen) RUST_LOG=warn mdbook build doc/manual -d $(docdir)/manual
-	@cp doc/manual/highlight.pack.js $(docdir)/manual/highlight.js
 
 endif

doc/manual/meson.build

@@ -0,0 +1,46 @@
+doc_manual_dir =  meson.current_source_dir()
+
+if get_option('doc_generate')
+
+    # Provide a dummy environment for nix, so that it will not access files outside the macOS sandbox.
+    dummy_env = [
+        'HOME=/dummy',
+        'NIX_CONF_DIR=/dummy',
+        'NIX_SSL_CERT_FILE=/dummy/no-ca-bundle.crt',
+        'NIX_STATE_DIR=/dummy',
+    ]
+
+    foreach dir : ['src']
+        subdir(dir)
+    endforeach
+
+    # generate the web version of the manual
+    #============================================================================
+
+    custom_target(
+        'index.html',
+        input: src_markdown_files + [
+            summary_dot_md,
+            new_cli,
+            conf_file_dot_md,
+            builtins_dot_md,
+        ] + files(
+            'book.toml',
+            'custom.css',
+            join_paths('theme', 'highlight.js'),
+        ),
+        output: 'manual',
+        command: [
+            'mdbook',
+            'build',
+            meson.current_build_dir(),
+            '-d',
+            'manual',
+        ],
+        env: ['RUST_LOG=warn'],
+        install: true,
+        install_dir: docdir,
+        build_by_default: true,
+    )
+
+endif

doc/manual/src/command-ref/meson.build

@@ -0,0 +1,160 @@
+doc_manual_src_command_ref_src =  meson.current_source_dir()
+
+# generate `doc/manual/src/command-ref/new-cli`
+#============================================================================
+
+nix_dot_json = custom_target(
+    'nix.json',
+    output: 'nix.json',
+    command: [
+        nix_bin,
+        '__dump-args',
+    ],
+    capture: true,
+    env: dummy_env,
+    install: true,
+    install_dir: mandir,
+    build_by_default: true,
+)
+
+new_cli = custom_target(
+    'new-cli',
+    input: [
+        nix_bin,
+        nix_dot_json,
+        join_paths(doc_manual_dir, 'generate-manpage.nix'),
+    ],
+    output: 'new-cli',
+    command: [
+        find_program(
+            'write-new-cli.sh',
+            dirs: [join_paths(scripts_dir, 'manual')],
+        ),
+        '@INPUT@',
+        '@OUTPUT@',
+    ],
+    env: dummy_env,
+    install: true,
+    install_dir: mandir,
+    build_by_default: true,
+)
+
+# generate `doc/manual/src/command-ref/conf-file.md`
+#============================================================================
+
+conf_file_dot_json = custom_target(
+    'conf-file.json',
+    output: 'conf-file.json',
+    command: [
+        nix_bin,
+        'show-config',
+        '--json',
+        '--experimental-features',
+        'nix-command',
+    ],
+    capture: true,
+    env: dummy_env,
+    install: true,
+    install_dir: mandir,
+    build_by_default: true,
+)
+
+conf_file_dot_md = custom_target(
+    'conf-file.md',
+    input: [
+        nix_bin,
+        conf_file_dot_json,
+        join_paths(doc_manual_dir, 'generate-options.nix')
+    ] + files(
+        'conf-file-prefix.md'
+    ),
+    output: 'conf-file.md',
+    command: [
+        find_program(
+            'write-conf-file.sh',
+            dirs: [join_paths(scripts_dir, 'manual')],
+        ),
+        '@INPUT@',
+    ],
+    capture: true,
+    install: true,
+    install_dir: mandir,
+    build_by_default: true,
+)
+
+# man pages
+#============================================================================
+
+prepend_title = generator(
+    find_program(
+        'prepend-title-to-manpage.sh',
+        dirs: [join_paths(scripts_dir, 'manual')],
+    ),
+    arguments: ['@BASENAME@', '@EXTRA_ARGS@', '@INPUT@'],
+    capture: true,
+    output: '@BASENAME@.tmp',
+)
+
+man_pages = {
+    '1': [
+        'nix-env',
+        'nix-build',
+        'nix-shell',
+        'nix-store',
+        'nix-instantiate',
+        'nix-collect-garbage',
+        'nix-prefetch-url',
+        'nix-channel',
+        'nix-hash',
+        'nix-copy-closure',
+    ],
+    '8': [
+        'nix-daemon',
+    ]
+}
+
+foreach section, pages : man_pages
+    foreach page : pages
+        man_dst = '@0@.@1@'.format(page, section)
+        man_src = files('@0@.md'.format(page))
+
+        custom_target(
+            man_dst,
+            input: prepend_title.process(man_src, extra_args: [section]),
+            output: man_dst,
+            command: [
+                'lowdown',
+                '-sT',
+                'man',
+                '-M section=@0@'.format(section),
+                '@INPUT@',
+                '-o',
+                '@OUTPUT@'
+            ],
+            install: true,
+            install_dir: mandir,
+            build_by_default: true,
+        )
+    endforeach
+endforeach
+
+custom_target(
+    'nix.conf.5',
+    input: prepend_title.process(
+        conf_file_dot_md,
+        extra_args: ['5']
+    ),
+    output: 'nix.conf.5',
+    command: [
+        'lowdown',
+        '-sT',
+        'man',
+        '-M section=5',
+        '@INPUT@',
+        '-o',
+        '@OUTPUT@',
+    ],
+    install: true,
+    install_dir: mandir,
+    build_by_default: true,
+)

doc/manual/src/expressions/meson.build

@@ -0,0 +1,42 @@
+doc_manual_src_expressions_dir =  meson.current_source_dir()
+
+# Generate `doc/manual/src/expressions/builtins.md`
+#============================================================================
+
+builtins_dot_json = custom_target(
+    'builtins.json',
+    output: 'builtins.json',
+    command: [
+        nix_bin,
+        '__dump-builtins',
+    ],
+    capture: true,
+    env: dummy_env + ['NIX_PATH=nix/corepkgs=corepkgs'],
+    install: true,
+    install_dir: mandir,
+    build_by_default: true,
+)
+
+builtins_dot_md = custom_target(
+    'builtins.md',
+    input: [
+        nix_bin,
+        builtins_dot_json,
+        join_paths(doc_manual_dir, 'generate-builtins.nix')
+    ] + files(
+        'builtins-prefix.md',
+        'builtins-suffix.md',
+    ),
+    output: 'builtins.md',
+    command: [
+        find_program(
+            'write-builtins.sh',
+            dirs: [join_paths(scripts_dir, 'manual')],
+        ),
+        '@INPUT@',
+    ],
+    capture: true,
+    install: true,
+    install_dir: mandir,
+    build_by_default: true,
+)

doc/manual/src/meson.build

@@ -0,0 +1,29 @@
+doc_manual_src_dir =  meson.current_source_dir()
+
+foreach dir : ['command-ref', 'expressions']
+    subdir(dir)
+endforeach
+
+# generate `doc/manual/src/SUMMARY.md`
+#============================================================================
+
+summary_dot_md = custom_target(
+    'SUMMARY.md',
+    input: [
+        join_paths(doc_manual_dir, 'src', 'SUMMARY.md.in'),
+        new_cli,
+    ],
+    output: 'SUMMARY.md',
+    command: [
+        find_program(
+            'write-summary.sh',
+            dirs: [join_paths(scripts_dir, 'manual')],
+        ),
+        '@INPUT@',
+    ],
+    capture: true,
+    install: true,
+    install_dir: mandir,
+    build_by_default: true,
+)
+

meson.build

@@ -91,6 +91,7 @@ datadir = join_paths(prefix, get_option('datadir'))
 sysconfdir = join_paths(prefix, get_option('sysconfdir'))
 libexecdir = join_paths(prefix, get_option('libexecdir'))
 mandir = join_paths(prefix, get_option('mandir'))
+docdir = join_paths(prefix, get_option('docdir'))
 includedir = join_paths(prefix, get_option('includedir'))
 proj_inc = []
 
@@ -225,8 +226,8 @@ project_dirs = [
     'include',
     'src',
     'scripts',
+    'doc/manual',
     #'misc',
-    #'doc',
     #'tests',
 ]
 

scripts/manual/prepend-title-to-manpage.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+# This script is meant to be used by `doc/manual/meson.build` to help build the documentation.
+
+printf "Title: %s\n\n" "${1}.${2}"
+cat $3

scripts/manual/write-builtins.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env sh
+# This script is meant to be used by `doc/manual/meson.build` to help build the documentation.
+
+nixBinary="$1"
+builtinsJsonFile="$2"
+generateBuiltinsNix="$3"
+prefixFile="$4"
+suffixFile="$5"
+
+cat $prefixFile
+
+$nixBinary eval \
+    --experimental-features nix-command \
+    -I nix/corepkgs=corepkgs \
+    --store dummy:// \
+    --impure \
+    --raw \
+    --expr "import $generateBuiltinsNix (builtins.fromJSON (builtins.readFile $builtinsJsonFile))"
+
+cat $suffixFile

scripts/manual/write-conf-file.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env sh
+# This script is meant to be used by `doc/manual/meson.build` to help build the documentation.
+
+nixBinary="$1"
+confJsonFile="$2"
+generateOptionsNix="$3"
+prefixFile="$4"
+
+
+cat $prefixFile
+
+$nixBinary eval \
+    --experimental-features nix-command \
+    -I nix/corepkgs=corepkgs \
+    --store dummy:// \
+    --impure \
+    --raw \
+    --expr "import $generateOptionsNix (builtins.fromJSON (builtins.readFile $confJsonFile))"

scripts/manual/write-new-cli.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+# This script is meant to be used by `doc/manual/meson.build` to help build the documentation.
+
+nixBinary="$1"
+newCliFile="$2"
+generateManPageNix="$3"
+output="$4"
+
+# `--write-to` requires the file to *NOT* be present.
+rm -Rf $output
+
+$nixBinary eval \
+    --experimental-features nix-command \
+    -I nix/corepkgs=corepkgs \
+    --store dummy:// \
+    --impure \
+    --raw \
+    --write-to $output \
+    --expr "import $generateManPageNix (builtins.fromJSON (builtins.readFile $newCliFile))"