From 6f72473b2457ecd449259dc6c283976cea8f0e13 Mon Sep 17 00:00:00 2001 From: Thibault Saunier Date: Tue, 14 Aug 2018 16:04:48 -0300 Subject: docs: Use meson to build documentation Let's eat our own dogfood. --- docs/README.md | 5 ++--- docs/hotdoc.json | 16 ---------------- docs/meson.build | 22 ++++++++++++++++++++++ 3 files changed, 24 insertions(+), 19 deletions(-) delete mode 100644 docs/hotdoc.json create mode 100644 docs/meson.build (limited to 'docs') diff --git a/docs/README.md b/docs/README.md index 9ed75c10b..18509c7ed 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 482bc95d1..000000000 --- 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/meson.build b/docs/meson.build new file mode 100644 index 000000000..c83d5f89f --- /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 -- cgit v1.2.3 From 1ea743a0bfd5ab3ab74009fdd0fb2db64e8e79d8 Mon Sep 17 00:00:00 2001 From: Thibault Saunier Date: Fri, 17 Aug 2018 20:13:08 -0300 Subject: 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 (limited to 'docs') 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")):
  • @tup[1]
    • -- cgit v1.2.3