Chiebot-Mirror
/
meson
8
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Hotdoc: use template for Commands.md instead of generating the entire file (#8154)

Browse Source 
* 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
pull/8181/head
Eli Schwartz 4 years ago committed by GitHub
parent 832bcac0a7
commit c18a9715b8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 38 additions and 102 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 88
      docs/markdown/Commands.md
  2. 20
      docs/meson.build
  3. 12
      run_unittests.py
  4. 20
      tools/regenerate_docs.py

88
docs/markdown_dynamic/Commands.md → docs/markdown/Commands.md
Unescape View File

@ -16,15 +16,11 @@ For the full list of all available options for a specific command use the follow
### configure ### configure
``` {{ configure_usage.inc }}
{{ cmd_help['configure']['usage'] }}
```
Changes options of a configured meson project. Changes options of a configured meson project.
``` {{ configure_arguments.inc }}
{{ cmd_help['configure']['arguments'] }}
```
Most arguments are the same as in [`setup`](#setup). Most arguments are the same as in [`setup`](#setup).
@ -46,15 +42,11 @@ meson configure builddir -Doption=new_value
*(since 0.54.0)* *(since 0.54.0)*
``` {{ compile_usage.inc }}
{{ cmd_help['compile']['usage'] }}
```
Builds a default or a specified target of a configured meson project. Builds a default or a specified target of a configured meson project.
``` {{ compile_arguments.inc }}
{{ cmd_help['compile']['arguments'] }}
```
`--verbose` argument is available since 0.55.0. `--verbose` argument is available since 0.55.0.
@ -115,15 +107,11 @@ meson compile coverage-html
*(since 0.52.0)* *(since 0.52.0)*
``` {{ dist_usage.inc }}
{{ cmd_help['dist']['usage'] }}
```
Generates a release archive from the current source tree. Generates a release archive from the current source tree.
``` {{ dist_arguments.inc }}
{{ cmd_help['dist']['arguments'] }}
```
See [notes about creating releases](Creating-releases.md) for more info. See [notes about creating releases](Creating-releases.md) for more info.
@ -138,15 +126,11 @@ meson dist -C builddir
*(since 0.45.0)* *(since 0.45.0)*
``` {{ init_usage.inc }}
{{ cmd_help['init']['usage'] }}
```
Creates a basic set of build files based on a template. Creates a basic set of build files based on a template.
``` {{ init_arguments.inc }}
{{ cmd_help['init']['arguments'] }}
```
#### Examples: #### Examples:
@ -157,15 +141,11 @@ meson init -C sourcedir
### introspect ### introspect
``` {{ introspect_usage.inc }}
{{ cmd_help['introspect']['usage'] }}
```
Displays information about a configured meson project. Displays information about a configured meson project.
``` {{ introspect_arguments.inc }}
{{ cmd_help['introspect']['arguments'] }}
```
#### Examples: #### Examples:
@ -178,15 +158,11 @@ meson introspect builddir
*(since 0.47.0)* *(since 0.47.0)*
``` {{ install_usage.inc }}
{{ cmd_help['install']['usage'] }}
```
Installs the project to the prefix specified in [`setup`](#setup). Installs the project to the prefix specified in [`setup`](#setup).
``` {{ install_arguments.inc }}
{{ cmd_help['install']['arguments'] }}
```
See [the installation documentation](Installing.md) for more info. See [the installation documentation](Installing.md) for more info.
@ -206,31 +182,23 @@ DESTDIR=/path/to/staging/area meson install -C builddir
*(since 0.50.0)* *(since 0.50.0)*
``` {{ rewrite_usage.inc }}
{{ cmd_help['rewrite']['usage'] }}
```
Modifies the meson project. Modifies the meson project.
``` {{ rewrite_arguments.inc }}
{{ cmd_help['rewrite']['arguments'] }}
```
See [the meson file rewriter documentation](Rewriter.md) for more info. See [the meson file rewriter documentation](Rewriter.md) for more info.
### setup ### setup
``` {{ setup_usage.inc }}
{{ cmd_help['setup']['usage'] }}
```
Configures a build directory for the meson project. Configures a build directory for the meson project.
This is the default meson command (invoked if there was no COMMAND supplied). This is the default meson command (invoked if there was no COMMAND supplied).
``` {{ setup_arguments.inc }}
{{ cmd_help['setup']['arguments'] }}
```
See [meson introduction page](Running-Meson.md#configuring-the-build-directory) for more info. See [meson introduction page](Running-Meson.md#configuring-the-build-directory) for more info.
@ -245,27 +213,19 @@ meson setup builddir
*(since 0.49.0)* *(since 0.49.0)*
``` {{ subprojects_usage.inc }}
{{ cmd_help['subprojects']['usage'] }}
```
Manages subprojects of the meson project. Manages subprojects of the meson project.
``` {{ subprojects_arguments.inc }}
{{ cmd_help['subprojects']['arguments'] }}
```
### test ### test
``` {{ test_usage.inc }}
{{ cmd_help['test']['usage'] }}
```
Run tests for the configure meson project. Run tests for the configure meson project.
``` {{ test_arguments.inc }}
{{ cmd_help['test']['arguments'] }}
```
See [the unit test documentation](Unit-tests.md) for more info. See [the unit test documentation](Unit-tests.md) for more info.
@ -283,14 +243,10 @@ meson test -C builddir specific_test_1 specific_test_2
### wrap ### wrap
``` {{ wrap_usage.inc }}
{{ cmd_help['wrap']['usage'] }}
```
An utility to manage WrapDB dependencies. An utility to manage WrapDB dependencies.
``` {{ wrap_arguments.inc }}
{{ cmd_help['wrap']['arguments'] }}
```
See [the WrapDB tool documentation](Using-wraptool.md) for more info. See [the WrapDB tool documentation](Using-wraptool.md) for more info.

20
docs/meson.build
Unescape View File

@ -2,22 +2,14 @@ project('Meson documentation', version: '1.0')
cur_bdir = meson.current_build_dir() 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 # Only the script knows which files are being generated
docs_gen = custom_target( docs_gen = custom_target(
'gen_docs', 'gen_docs',
input: files('markdown/index.md'), input: files('markdown/index.md'),
output: 'gen_docs.dummy', output: 'gen_docs.stamp',
command: [ command: [
files('../tools/regenerate_docs.py'), files('../tools/regenerate_docs.py'),
'--output-dir', join_paths(cur_bdir, 'markdown'), '--output-dir', cur_bdir,
'--dummy-output-file', '@OUTPUT@', '--dummy-output-file', '@OUTPUT@',
], ],
build_by_default: true, build_by_default: true,
@ -26,15 +18,15 @@ docs_gen = custom_target(
hotdoc = import('hotdoc') hotdoc = import('hotdoc')
documentation = hotdoc.generate_doc(meson.project_name(), documentation = hotdoc.generate_doc(meson.project_name(),
project_version: meson.project_version(), project_version: meson.project_version(),
sitemap: join_paths(cur_bdir, 'sitemap.txt'), sitemap: 'sitemap.txt',
build_by_default: true, build_by_default: true,
depends: docs_gen, depends: docs_gen,
index: join_paths(cur_bdir, 'markdown/index.md'), index: 'markdown/index.md',
install: false, install: false,
extra_assets: ['images/'], extra_assets: ['images/'],
include_paths: [join_paths(cur_bdir, 'markdown')], include_paths: ['markdown', cur_bdir],
default_license: 'CC-BY-SAv4.0', 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', git_upload_repository: 'git@github.com:jpakkane/jpakkane.github.io.git',
edit_on_github_repository: 'https://github.com/mesonbuild/meson', edit_on_github_repository: 'https://github.com/mesonbuild/meson',
syntax_highlighting_activate: true, syntax_highlighting_activate: true,

12
run_unittests.py
Unescape View File

@ -4915,7 +4915,7 @@ class AllPlatformTests(BasePlatformTests):
# The docs directory is not in release tarballs. # The docs directory is not in release tarballs.
if not os.path.isdir('docs'): if not os.path.isdir('docs'):
raise unittest.SkipTest('Doc directory does not exist.') raise unittest.SkipTest('Doc directory does not exist.')
doc_path = 'docs/markdown_dynamic/Commands.md' doc_path = 'docs/markdown/Commands.md'
md = None md = None
with open(doc_path, encoding='utf-8') as f: with open(doc_path, encoding='utf-8') as f:
@ -4944,13 +4944,9 @@ class AllPlatformTests(BasePlatformTests):
def get_data_pattern(command): def get_data_pattern(command):
return re.compile( return re.compile(
r'^```[\r\n]' r'{{ ' + command + r'_usage.inc }}[\r\n]'
r'{{ cmd_help\[\'' + command + r'\'\]\[\'usage\'\] }}[\r\n]'
r'^```[\r\n]'
r'.*?' r'.*?'
r'^```[\r\n]' r'{{ ' + command + r'_arguments.inc }}[\r\n]',
r'{{ cmd_help\[\'' + command + r'\'\]\[\'arguments\'\] }}[\r\n]'
r'^```',
flags = re.MULTILINE|re.DOTALL) flags = re.MULTILINE|re.DOTALL)
for command in md_commands: for command in md_commands:
@ -7533,7 +7529,7 @@ class LinuxCrossArmTests(BaseLinuxCrossTests):
'-Dbuild.pkg_config_path=' + os.path.join(testdir, 'build_extra_path'), '-Dbuild.pkg_config_path=' + os.path.join(testdir, 'build_extra_path'),
'-Dpkg_config_path=' + os.path.join(testdir, 'host_extra_path'), '-Dpkg_config_path=' + os.path.join(testdir, 'host_extra_path'),
]) ])
def test_run_native_test(self): def test_run_native_test(self):
''' '''
https://github.com/mesonbuild/meson/issues/7997 https://github.com/mesonbuild/meson/issues/7997

20
tools/regenerate_docs.py
Unescape View File

@ -20,7 +20,6 @@ Regenerate markdown docs by using `meson.py` from the root dir
''' '''
import argparse import argparse
import jinja2
import os import os
import re import re
import subprocess import subprocess
@ -108,20 +107,13 @@ def get_commands_data(root_dir: Path) -> T.Dict[str, T.Any]:
return cmd_data return cmd_data
def regenerate_commands(root_dir: Path, output_dir: Path) -> None: def generate_hotdoc_includes(root_dir: Path, output_dir: Path) -> None:
with open(root_dir/'docs'/'markdown_dynamic'/'Commands.md') as f:
template = f.read()
cmd_data = get_commands_data(root_dir) cmd_data = get_commands_data(root_dir)
t = jinja2.Template(template, undefined=jinja2.StrictUndefined, keep_trailing_newline=True) for cmd, parsed in cmd_data.items():
content = t.render(cmd_help=cmd_data) for typ in parsed.keys():
with open(output_dir / (cmd+'_'+typ+'.inc'), 'w') as f:
output_file = output_dir/'Commands.md' f.write(parsed[typ])
with open(output_file, 'w') as f:
f.write(content)
print(f'`{output_file}` was regenerated')
def regenerate_docs(output_dir: PathLike, def regenerate_docs(output_dir: PathLike,
dummy_output_file: T.Optional[PathLike]) -> None: dummy_output_file: T.Optional[PathLike]) -> None:
@ -133,7 +125,7 @@ def regenerate_docs(output_dir: PathLike,
root_dir = Path(__file__).resolve().parent.parent root_dir = Path(__file__).resolve().parent.parent
regenerate_commands(root_dir, output_dir) generate_hotdoc_includes(root_dir, output_dir)
if dummy_output_file: if dummy_output_file:
with open(output_dir/dummy_output_file, 'w') as f: with open(output_dir/dummy_output_file, 'w') as f:

Write Preview
Loading…
Cancel
Save