modules: Add an 'hotdoc' module

ciimage/Dockerfile

@@ -12,6 +12,7 @@ RUN apt-get -y update && apt-get -y upgrade \
 && apt-get -y install qt4-linguist-tools \
 && apt-get -y install python-dev \
 && apt-get -y install libomp-dev openssh-client \
+&& apt-get -y install -y clang libclang-dev llvm-dev flex \
 && python3 -m pip install hotdoc codecov \
 && dub fetch urld \
 && dub build urld --compiler=gdc

docs/README.md

@@ -3,7 +3,7 @@
 1. Get [hotdoc](https://hotdoc.github.io/installing.html) (0.8.9 required)
 1. Run hotdoc in the docs/ directory:
 
-    hotdoc run
+    ../meson/meson.py build/
 
 ## Upload
 
@@ -12,5 +12,4 @@ removes the html pages and replaces with the new content.
 
 You can simply run:
 
-    hotdoc run --git-upload-activate
-
+    ninja -C build/ upload

docs/markdown/Hotdoc-module.md

@@ -0,0 +1,79 @@
+---
+short-description: Hotdoc module
+authors:
+    - name: Thibault Saunier
+      email: [email protected]
+      years: [2018]
+      has-copyright: false
+...
+
+# Hotdoc module
+
+This module provides helper functions for generating documentation using
+[hotdoc].
+
+*Added 0.48.0*
+
+## Usage
+
+To use this module, just do: **`hotdoc = import('hotdoc')`**. The
+following functions will then be available as methods on the object
+with the name `hotdoc`. You can, of course, replace the name `hotdoc`
+with anything else.
+
+### hotdoc.generate_doc()
+
+Generates documentation using [hotdoc] and installs it into `$prefix/share/doc/html`.
+
+**Positional argument:**
+
+* `project_name`: The name of the hotdoc project
+
+**Keyworded arguments:**
+
+* `sitemap` (*[string] or [file]*) (**required**): The hotdoc sitemap file
+* `index` (*[string] or [file]*) (**required**): Location of the index file
+* `dependencies`(*[targets]*): Targets on which the documentation generation depends on.
+* `subprojects`: A list of `HotdocTarget` that are used as subprojects for hotdoc to generate
+  the documentation.
+* ... Any argument of `hotdoc` can be used replacing dashes (`-`) with underscores (`_`).
+  For a full list of available parameters, just have a look at `hotdoc help`.
+
+[file]: Reference-manual.md#files
+[string]: Reference-manual.md#string-object
+[targets]: Reference-manual.md#build-target-object
+
+**Returns:**
+
+`HotdocTarget`: A [`custom_target`](Reference-manual.md#custom-target-object) with the
+following extra methods:
+
+* `config_path`: Path to the generated `hotdoc` configuration file.
+
+### hotdoc.has_extensions()
+
+**Positional arguments:**
+
+* `...`: The hotdoc extension names to look for
+
+**No keyworded arguments**
+
+**Returns:** `true` if all the extensions where found, `false` otherwise.
+
+### Example
+
+``` meson
+hotdoc = import('hotdoc')
+
+hotdoc.generate_doc('foobar',
+  project_version: '0.1',
+  sitemap: 'sitemap.txt',
+  index: 'index.md',
+  c_sources: ['path/to/file.c'],
+  c_smart_index: true,
+  languages: ['c'],
+  install: true,
+)
+```
+
+[hotdoc]: https://hotdoc.github.io/

docs/markdown/snippets/hotdoc_module.md

@@ -0,0 +1,22 @@
+## Hotdoc module
+
+A new module has been written to ease generation of [hotdoc](https://hotdoc.github.io/) based
+documentation. It supports complex use cases such as hotdoc subprojects (to create documentation
+portals) and makes it straight forward to leverage full capabilities of hotdoc.
+
+Simple usage:
+
+``` meson
+hotdoc = import('hotdoc')
+
+hotdoc.generate_doc(
+  'foobar',
+  c_smart_index: true,
+  project_version: '0.1',
+  sitemap: 'sitemap.txt',
+  index: 'index.md',
+  c_sources: ['path/to/file.c'],
+  languages: ['c'],
+  install: true,
+)
+```

docs/meson.build

@@ -0,0 +1,22 @@
+project('Meson documentation', version: '1.0')
+
+hotdoc = import('hotdoc')
+documentation = hotdoc.generate_doc(meson.project_name(),
+    project_version: meson.project_version(),
+    sitemap: 'sitemap.txt',
+    build_by_default: true,
+    index: 'markdown/index.md',
+    install: false,
+    extra_assets: ['images/'],
+    include_paths: ['markdown'],
+    default_license: 'CC-BY-SAv4.0',
+    html_extra_theme: join_paths('theme', 'extra'),
+    git_upload_repository: '[email protected]:jpakkane/jpakkane.github.io.git',
+    edit_on_github_repository: 'https://github.com/mesonbuild/meson/',
+    syntax_highlighting_activate: true,
+)
+
+run_target('upload',
+    command: [find_program('hotdoc'), 'run', '--conf-file', documentation.config_path(),
+              '--git-upload']
+)

docs/sitemap.txt

@@ -29,7 +29,9 @@ index.md
 		Subprojects.md
 		Disabler.md
 		Modules.md
+			Dlang-module.md
 			Gnome-module.md
+			Hotdoc-module.md
 			i18n-module.md
 			Icestorm-module.md
 			Pkgconfig-module.md
@@ -40,7 +42,6 @@ index.md
 			RPM-module.md
 			Simd-module.md
 			Windows-module.md
-			Dlang-module.md
 		Java.md
 		Vala.md
 		D.md

docs/theme/extra/templates/navbar_links.html

@@ -13,7 +13,8 @@
 			     ("Qt4-module.html","Qt4"), \
 			     ("Qt5-module.html","Qt5"), \
 			     ("RPM-module.html","RPM"), \
-			     ("Windows-module.html","Windows")):
+			     ("Windows-module.html","Windows"), \
+			     ("Hotdoc-module.html","Hotdoc")):
 			<li>
 				<a href="@tup[0]">@tup[1]</a>
 			</li>

mesonbuild/build.py

@@ -1820,7 +1820,8 @@ def process_kwargs(self, kwargs):
             while hasattr(ed, 'held_object'):
                 ed = ed.held_object
             if not isinstance(ed, (CustomTarget, BuildTarget)):
-                raise InvalidArguments('Can only depend on toplevel targets: custom_target or build_target (executable or a library)')
+                raise InvalidArguments('Can only depend on toplevel targets: custom_target or build_target (executable or a library) got: %s(%s)'
+                                       % (type(ed), ed))
             self.extra_depends.append(ed)
         for i in depend_files:
             if isinstance(i, (File, str)):

mesonbuild/interpreter.py

@@ -1974,7 +1974,7 @@ def holderify(self, item):
             return [self.holderify(x) for x in item]
         if isinstance(item, build.CustomTarget):
             return CustomTargetHolder(item, self)
-        elif isinstance(item, (int, str)) or item is None:
+        elif isinstance(item, (int, str, bool)) or item is None:
             return item
         elif isinstance(item, build.Executable):
             return ExecutableHolder(item, self)
@@ -2000,6 +2000,9 @@ def holderify(self, item):
     def process_new_values(self, invalues):
         invalues = listify(invalues)
         for v in invalues:
+            if isinstance(v, (RunTargetHolder, CustomTargetHolder, BuildTargetHolder)):
+                v = v.held_object
+
             if isinstance(v, (build.BuildTarget, build.CustomTarget, build.RunTarget)):
                 self.add_target(v.name, v)
             elif isinstance(v, list):
@@ -2018,6 +2021,8 @@ def process_new_values(self, invalues):
                 self.process_new_values(v.sources[0])
             elif hasattr(v, 'held_object'):
                 pass
+            elif isinstance(v, (int, str, bool)):
+                pass
             else:
                 raise InterpreterException('Module returned a value of unknown type.')
 

mesonbuild/mesonmain.py

@@ -200,6 +200,9 @@ def run_script_command(args):
     elif cmdname == 'msgfmthelper':
         import mesonbuild.scripts.msgfmthelper as abc
         cmdfunc = abc.run
+    elif cmdname == 'hotdoc':
+        import mesonbuild.scripts.hotdochelper as abc
+        cmdfunc = abc.run
     elif cmdname == 'regencheck':
         import mesonbuild.scripts.regen_checker as abc
         cmdfunc = abc.run