Merge pull request #4016 from thiblahute/hotdoc

modules: Add an 'hotdoc' module

7 files changed, 129 insertions, 21 deletions

diff --git a/docs/README.md b/docs/README.md
index 9ed75c1..18509c7 100644
--- a/docs/README.md
+++ b/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
diff --git a/docs/hotdoc.json b/docs/hotdoc.json
deleted file mode 100644
index 482bc95..0000000
--- a/docs/hotdoc.json
+++ /dev/null
@@ -1,16 +0,0 @@
-{
-    "extra_assets": [
-        "images/"
-    ],
-    "html_extra_theme": "theme/extra/",
-    "include_paths": [
-        "markdown/"
-    ],
-    "output": "built_docs/",
-    "project_name": "Meson documentation",
-    "project_version": "1.0",
-    "default-license": "CC-BY-SAv4.0",
-    "sitemap": "sitemap.txt",
-    "git_upload_repository": "git@github.com:jpakkane/jpakkane.github.io.git",
-    "edit_on_github_repository": "https://github.com/mesonbuild/meson/"
-}
diff --git a/docs/markdown/Hotdoc-module.md b/docs/markdown/Hotdoc-module.md
new file mode 100644
index 0000000..7d9fc55
--- /dev/null
+++ b/docs/markdown/Hotdoc-module.md
@@ -0,0 +1,79 @@
+---
+short-description: Hotdoc module
+authors:
+    - name: Thibault Saunier
+      email: tsaunier@igalia.com
+      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/
\ No newline at end of file
diff --git a/docs/markdown/snippets/hotdoc_module.md b/docs/markdown/snippets/hotdoc_module.md
new file mode 100644
index 0000000..4662ea2
--- /dev/null
+++ b/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,
+)
+```
\ No newline at end of file
diff --git a/docs/meson.build b/docs/meson.build
new file mode 100644
index 0000000..c83d5f8
--- /dev/null
+++ b/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: 'git@github.com: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']
+)
\ No newline at end of file
diff --git a/docs/sitemap.txt b/docs/sitemap.txt
index 2d43e18..4ba1b90 100644
--- a/docs/sitemap.txt
+++ b/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
diff --git a/docs/theme/extra/templates/navbar_links.html b/docs/theme/extra/templates/navbar_links.html
index 2edce24..c9cba13 100644
--- a/docs/theme/extra/templates/navbar_links.html
+++ b/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>