From 1ea743a0bfd5ab3ab74009fdd0fb2db64e8e79d8 Mon Sep 17 00:00:00 2001
From: Thibault Saunier <tsaunier@igalia.com>
Date: Fri, 17 Aug 2018 20:13:08 -0300
Subject: [PATCH] hotdoc: Add documentation

---
 docs/markdown/Hotdoc-module.md               | 79 ++++++++++++++++++++
 docs/markdown/snippets/hotdoc_module.md      | 22 ++++++
 docs/sitemap.txt                             |  3 +-
 docs/theme/extra/templates/navbar_links.html |  3 +-
 4 files changed, 105 insertions(+), 2 deletions(-)
 create mode 100644 docs/markdown/Hotdoc-module.md
 create mode 100644 docs/markdown/snippets/hotdoc_module.md

diff --git a/docs/markdown/Hotdoc-module.md b/docs/markdown/Hotdoc-module.md
new file mode 100644
index 000000000..7d9fc555f
--- /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 000000000..4662ea22b
--- /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/sitemap.txt b/docs/sitemap.txt
index 2d43e1806..4ba1b90df 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 2edce2489..c9cba131d 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>