From c18a9715b83ef94a56c064edee511162998001cc Mon Sep 17 00:00:00 2001
From: Eli Schwartz <eschwartz@archlinux.org>
Date: Sun, 10 Jan 2021 07:48:34 -0500
Subject: Hotdoc: use template for Commands.md instead of generating the entire
 file (#8154)

* doc: fix hotdoc misuse for dynamically generated content

hotdoc has a native include feature for including files inline. Use this
to generate one file for each dynamically generated code block, and
include that file in Commands.md; see:
https://hotdoc.github.io/syntax-extensions.html#smart-file-inclusion-syntax

This permits us to move back to using the in-tree version of the hotdoc
*.md sources, thus fixing the incorrect inclusion of "builddir/" in the
"Edit on github" links which resulted from using copies as the source.

Fixes #8061

* doc: call the dummy file a "stamp" as it is a better known term
---
 docs/markdown/Commands.md         | 252 ++++++++++++++++++++++++++++++++
 docs/markdown_dynamic/Commands.md | 296 --------------------------------------
 docs/meson.build                  |  20 +--
 3 files changed, 258 insertions(+), 310 deletions(-)
 create mode 100644 docs/markdown/Commands.md
 delete mode 100644 docs/markdown_dynamic/Commands.md

(limited to 'docs')

diff --git a/docs/markdown/Commands.md b/docs/markdown/Commands.md
new file mode 100644
index 0000000..46bd21b
--- /dev/null
+++ b/docs/markdown/Commands.md
@@ -0,0 +1,252 @@
+# Command-line commands
+
+There are two different ways of invoking Meson. First, you can run it directly
+from the source tree with the command `/path/to/source/meson.py`. Meson may
+also be installed in which case the command is simply `meson`. In this manual
+we only use the latter format for simplicity.
+
+Meson is invoked using the following syntax:
+`meson [COMMAND] [COMMAND_OPTIONS]`
+
+This section describes all available commands and some of their Optional arguments.
+The most common workflow is to run [`setup`](#setup), followed by [`compile`](#compile), and then [`install`](#install).
+
+For the full list of all available options for a specific command use the following syntax:
+`meson COMMAND --help`
+
+### configure
+
+{{ configure_usage.inc }}
+
+Changes options of a configured meson project.
+
+{{ configure_arguments.inc }}
+
+Most arguments are the same as in [`setup`](#setup).
+
+Note: reconfiguring project will not reset options to their default values (even if they were changed in `meson.build`).
+
+#### Examples:
+
+List all available options:
+```
+meson configure builddir
+```
+
+Change value of a single option:
+```
+meson configure builddir -Doption=new_value
+```
+
+### compile
+
+*(since 0.54.0)*
+
+{{ compile_usage.inc }}
+
+Builds a default or a specified target of a configured meson project.
+
+{{ compile_arguments.inc }}
+
+`--verbose` argument is available since 0.55.0.
+
+#### Targets
+
+*(since 0.55.0)*
+
+`TARGET` has the following syntax `[PATH/]NAME[:TYPE]`, where:
+- `NAME`: name of the target from `meson.build` (e.g. `foo` from `executable('foo', ...)`).
+- `PATH`: path to the target relative to the root `meson.build` file. Note: relative path for a target specified in the root `meson.build` is `./`.
+- `TYPE`: type of the target. Can be one of the following: 'executable', 'static_library', 'shared_library', 'shared_module', 'custom', 'run', 'jar'.
+  
+`PATH` and/or `TYPE` can be ommited if the resulting `TARGET` can be used to uniquely identify the target in `meson.build`.
+
+#### Backend specific arguments
+
+*(since 0.55.0)*
+
+`BACKEND-args` use the following syntax:
+
+If you only pass a single string, then it is considered to have all values separated by commas. Thus invoking the following command:
+
+```
+$ meson compile --ninja-args=-n,-d,explain
+```
+
+would add `-n`, `-d` and `explain` arguments to ninja invocation.
+
+If you need to have commas or spaces in your string values, then you need to pass the value with proper shell quoting like this:
+
+```
+$ meson compile "--ninja-args=['a,b', 'c d']"
+```
+
+#### Examples:
+
+Build the project:
+```
+meson compile -C builddir
+```
+
+Execute a dry run on ninja backend with additional debug info:
+```
+meson compile --ninja-args=-n,-d,explain
+```
+
+Build three targets: two targets that have the same `foo` name, but different type, and a `bar` target:
+```
+meson compile foo:shared_library foo:static_library bar
+```
+
+Produce a coverage html report (if available):
+```
+meson compile coverage-html
+```
+
+### dist
+
+*(since 0.52.0)*
+
+{{ dist_usage.inc }}
+
+Generates a release archive from the current source tree.
+
+{{ dist_arguments.inc }}
+
+See [notes about creating releases](Creating-releases.md) for more info.
+
+#### Examples:
+
+Create a release archive:
+```
+meson dist -C builddir
+```
+
+### init
+
+*(since 0.45.0)*
+
+{{ init_usage.inc }}
+
+Creates a basic set of build files based on a template.
+
+{{ init_arguments.inc }}
+
+#### Examples:
+
+Create a project in `sourcedir`:
+```
+meson init -C sourcedir
+```
+
+### introspect
+
+{{ introspect_usage.inc }}
+
+Displays information about a configured meson project.
+
+{{ introspect_arguments.inc }}
+
+#### Examples:
+
+Display basic information about a configured project in `builddir`:
+```
+meson introspect builddir
+```
+
+### install
+
+*(since 0.47.0)*
+
+{{ install_usage.inc }}
+
+Installs the project to the prefix specified in [`setup`](#setup).
+
+{{ install_arguments.inc }}
+
+See [the installation documentation](Installing.md) for more info.
+
+#### Examples:
+
+Install project to `prefix`:
+```
+meson install -C builddir
+```
+
+Install project to `$DESTDIR/prefix`:
+```
+DESTDIR=/path/to/staging/area meson install -C builddir
+```
+
+### rewrite
+
+*(since 0.50.0)*
+
+{{ rewrite_usage.inc }}
+
+Modifies the meson project.
+
+{{ rewrite_arguments.inc }}
+
+See [the meson file rewriter documentation](Rewriter.md) for more info.
+
+### setup
+
+{{ setup_usage.inc }}
+
+Configures a build directory for the meson project.
+
+This is the default meson command (invoked if there was no COMMAND supplied).
+
+{{ setup_arguments.inc }}
+
+See [meson introduction page](Running-Meson.md#configuring-the-build-directory) for more info.
+
+#### Examples:
+
+Configures `builddir` with default values:
+```
+meson setup builddir
+```
+
+### subprojects
+
+*(since 0.49.0)*
+
+{{ subprojects_usage.inc }}
+
+Manages subprojects of the meson project.
+
+{{ subprojects_arguments.inc }}
+
+### test
+
+{{ test_usage.inc }}
+
+Run tests for the configure meson project.
+
+{{ test_arguments.inc }}
+
+See [the unit test documentation](Unit-tests.md) for more info.
+
+#### Examples:
+
+Run tests for the project:
+```
+meson test -C builddir
+```
+
+Run only `specific_test_1` and `specific_test_2`:
+```
+meson test -C builddir specific_test_1 specific_test_2
+```
+
+### wrap
+
+{{ wrap_usage.inc }}
+
+An utility to manage WrapDB dependencies.
+
+{{ wrap_arguments.inc }}
+
+See [the WrapDB tool documentation](Using-wraptool.md) for more info.
diff --git a/docs/markdown_dynamic/Commands.md b/docs/markdown_dynamic/Commands.md
deleted file mode 100644
index a35b4da..0000000
--- a/docs/markdown_dynamic/Commands.md
+++ /dev/null
@@ -1,296 +0,0 @@
-# Command-line commands
-
-There are two different ways of invoking Meson. First, you can run it directly
-from the source tree with the command `/path/to/source/meson.py`. Meson may
-also be installed in which case the command is simply `meson`. In this manual
-we only use the latter format for simplicity.
-
-Meson is invoked using the following syntax:
-`meson [COMMAND] [COMMAND_OPTIONS]`
-
-This section describes all available commands and some of their Optional arguments.
-The most common workflow is to run [`setup`](#setup), followed by [`compile`](#compile), and then [`install`](#install).
-
-For the full list of all available options for a specific command use the following syntax:
-`meson COMMAND --help`
-
-### configure
-
-```
-{{ cmd_help['configure']['usage'] }}
-```
-
-Changes options of a configured meson project.
-
-```
-{{ cmd_help['configure']['arguments'] }}
-```
-
-Most arguments are the same as in [`setup`](#setup).
-
-Note: reconfiguring project will not reset options to their default values (even if they were changed in `meson.build`).
-
-#### Examples:
-
-List all available options:
-```
-meson configure builddir
-```
-
-Change value of a single option:
-```
-meson configure builddir -Doption=new_value
-```
-
-### compile
-
-*(since 0.54.0)*
-
-```
-{{ cmd_help['compile']['usage'] }}
-```
-
-Builds a default or a specified target of a configured meson project.
-
-```
-{{ cmd_help['compile']['arguments'] }}
-```
-
-`--verbose` argument is available since 0.55.0.
-
-#### Targets
-
-*(since 0.55.0)*
-
-`TARGET` has the following syntax `[PATH/]NAME[:TYPE]`, where:
-- `NAME`: name of the target from `meson.build` (e.g. `foo` from `executable('foo', ...)`).
-- `PATH`: path to the target relative to the root `meson.build` file. Note: relative path for a target specified in the root `meson.build` is `./`.
-- `TYPE`: type of the target. Can be one of the following: 'executable', 'static_library', 'shared_library', 'shared_module', 'custom', 'run', 'jar'.
-  
-`PATH` and/or `TYPE` can be ommited if the resulting `TARGET` can be used to uniquely identify the target in `meson.build`.
-
-#### Backend specific arguments
-
-*(since 0.55.0)*
-
-`BACKEND-args` use the following syntax:
-
-If you only pass a single string, then it is considered to have all values separated by commas. Thus invoking the following command:
-
-```
-$ meson compile --ninja-args=-n,-d,explain
-```
-
-would add `-n`, `-d` and `explain` arguments to ninja invocation.
-
-If you need to have commas or spaces in your string values, then you need to pass the value with proper shell quoting like this:
-
-```
-$ meson compile "--ninja-args=['a,b', 'c d']"
-```
-
-#### Examples:
-
-Build the project:
-```
-meson compile -C builddir
-```
-
-Execute a dry run on ninja backend with additional debug info:
-```
-meson compile --ninja-args=-n,-d,explain
-```
-
-Build three targets: two targets that have the same `foo` name, but different type, and a `bar` target:
-```
-meson compile foo:shared_library foo:static_library bar
-```
-
-Produce a coverage html report (if available):
-```
-meson compile coverage-html
-```
-
-### dist
-
-*(since 0.52.0)*
-
-```
-{{ cmd_help['dist']['usage'] }}
-```
-
-Generates a release archive from the current source tree.
-
-```
-{{ cmd_help['dist']['arguments'] }}
-```
-
-See [notes about creating releases](Creating-releases.md) for more info.
-
-#### Examples:
-
-Create a release archive:
-```
-meson dist -C builddir
-```
-
-### init
-
-*(since 0.45.0)*
-
-```
-{{ cmd_help['init']['usage'] }}
-```
-
-Creates a basic set of build files based on a template.
-
-```
-{{ cmd_help['init']['arguments'] }}
-```
-
-#### Examples:
-
-Create a project in `sourcedir`:
-```
-meson init -C sourcedir
-```
-
-### introspect
-
-```
-{{ cmd_help['introspect']['usage'] }}
-```
-
-Displays information about a configured meson project.
-
-```
-{{ cmd_help['introspect']['arguments'] }}
-```
-
-#### Examples:
-
-Display basic information about a configured project in `builddir`:
-```
-meson introspect builddir
-```
-
-### install
-
-*(since 0.47.0)*
-
-```
-{{ cmd_help['install']['usage'] }}
-```
-
-Installs the project to the prefix specified in [`setup`](#setup).
-
-```
-{{ cmd_help['install']['arguments'] }}
-```
-
-See [the installation documentation](Installing.md) for more info.
-
-#### Examples:
-
-Install project to `prefix`:
-```
-meson install -C builddir
-```
-
-Install project to `$DESTDIR/prefix`:
-```
-DESTDIR=/path/to/staging/area meson install -C builddir
-```
-
-### rewrite
-
-*(since 0.50.0)*
-
-```
-{{ cmd_help['rewrite']['usage'] }}
-```
-
-Modifies the meson project.
-
-```
-{{ cmd_help['rewrite']['arguments'] }}
-```
-
-See [the meson file rewriter documentation](Rewriter.md) for more info.
-
-### setup
-
-```
-{{ cmd_help['setup']['usage'] }}
-```
-
-Configures a build directory for the meson project.
-
-This is the default meson command (invoked if there was no COMMAND supplied).
-
-```
-{{ cmd_help['setup']['arguments'] }}
-```
-
-See [meson introduction page](Running-Meson.md#configuring-the-build-directory) for more info.
-
-#### Examples:
-
-Configures `builddir` with default values:
-```
-meson setup builddir
-```
-
-### subprojects
-
-*(since 0.49.0)*
-
-```
-{{ cmd_help['subprojects']['usage'] }}
-```
-
-Manages subprojects of the meson project.
-
-```
-{{ cmd_help['subprojects']['arguments'] }}
-```
-
-### test
-
-```
-{{ cmd_help['test']['usage'] }}
-```
-
-Run tests for the configure meson project.
-
-```
-{{ cmd_help['test']['arguments'] }}
-```
-
-See [the unit test documentation](Unit-tests.md) for more info.
-
-#### Examples:
-
-Run tests for the project:
-```
-meson test -C builddir
-```
-
-Run only `specific_test_1` and `specific_test_2`:
-```
-meson test -C builddir specific_test_1 specific_test_2
-```
-
-### wrap
-
-```
-{{ cmd_help['wrap']['usage'] }}
-```
-
-An utility to manage WrapDB dependencies.
-
-```
-{{ cmd_help['wrap']['arguments'] }}
-```
-
-See [the WrapDB tool documentation](Using-wraptool.md) for more info.
diff --git a/docs/meson.build b/docs/meson.build
index 496588d..fa80512 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -2,22 +2,14 @@ project('Meson documentation', version: '1.0')
 
 cur_bdir = meson.current_build_dir()
 
-# Copy all files to build dir, since HotDoc uses relative paths
-run_command(
-    files('../tools/copy_files.py'),
-    '-C', meson.current_source_dir(),
-    '--output-dir', cur_bdir,
-    'markdown', 'theme', 'sitemap.txt', 
-    check: true)
-
 # Only the script knows which files are being generated
 docs_gen = custom_target(
     'gen_docs',
     input: files('markdown/index.md'),
-    output: 'gen_docs.dummy',
+    output: 'gen_docs.stamp',
     command: [
         files('../tools/regenerate_docs.py'),
-        '--output-dir', join_paths(cur_bdir, 'markdown'),
+        '--output-dir', cur_bdir,
         '--dummy-output-file', '@OUTPUT@',
     ],
     build_by_default: true,
@@ -26,15 +18,15 @@ docs_gen = custom_target(
 hotdoc = import('hotdoc')
 documentation = hotdoc.generate_doc(meson.project_name(),
     project_version: meson.project_version(),
-    sitemap: join_paths(cur_bdir, 'sitemap.txt'),
+    sitemap: 'sitemap.txt',
     build_by_default: true,
     depends: docs_gen,
-    index: join_paths(cur_bdir, 'markdown/index.md'),
+    index: 'markdown/index.md',
     install: false,
     extra_assets: ['images/'],
-    include_paths: [join_paths(cur_bdir, 'markdown')],
+    include_paths: ['markdown', cur_bdir],
     default_license: 'CC-BY-SAv4.0',
-    html_extra_theme: join_paths(cur_bdir, 'theme', 'extra'),
+    html_extra_theme: join_paths('theme', 'extra'),
     git_upload_repository: 'git@github.com:jpakkane/jpakkane.github.io.git',
     edit_on_github_repository: 'https://github.com/mesonbuild/meson',
     syntax_highlighting_activate: true,
-- 
cgit v1.1