3 This is a collection of design documents, formerly maintained in various
4 different locations and formats, now grouped together and converted
11 We will follow the commonmark specification.
13 We *should* try to follow this
14 [style guide](http://www.cirosantilli.com/markdown-style-guide/#about),
15 but are still [evaluating solutions](https://github.com/jgm/cmark/issues/131)
16 for *stable* automatic formatting.
18 80 columns line width is thus not yet enforced, but strongly suggested.
20 # Build the documentation
22 ## Install dependencies
24 * Follow [hotdoc's installation guide](https://hotdoc.github.io/installing.html),
25 preferably in a virtualenv.
27 * We *experimentally* use the hotdoc C extension to include functions by
28 name, follow the steps outlined [here](https://github.com/hotdoc/hotdoc_c_extension)
30 ## Build the portal without the API documentation
34 ninja -C build/ GStreamer-doc
40 gio open build/GStreamer-doc/html/index.html
45 Building the API documentation in the portal implies using the full multi-repo
46 [gstreamer](https://gitlab.freedesktop.org/gstreamer/gstreamer/) build which
47 allows us to aggregate the documentation from all GStreamer modules using the
48 hotdoc subproject feature.
54 ./gst-env ninja -C build subprojects/gst-docs/GStreamer-doc
60 gio open build/subprojects/gst-docs/GStreamer-doc/html/index.html
63 You can also generate a release tarball of the portal with:
66 ninja -C build gst-docs@@release
69 ### Adding a newly written plugin to the documentation
71 To add a plugin to the documentation you need to add the given
72 meson target to the `plugins` list present in each GStreamer module for
76 gst_elements = library('gstcoreelements',
79 include_directories : [configinc],
80 dependencies : [gst_dep, gst_base_dep],
82 install_dir : plugins_install_dir,
84 plugins += [gst_elements]
87 Then you need to regenerate the `gst_plugins_cache.json` file by running
88 the target manually, if building from the module itself:
91 ninja -C <build-dir> docs/gst_plugins_cache.json
94 if you use the mono repo build there's also a target that will rebuild all
95 the cache files in the various GStreamer subprojects:
98 ninja -C <build-dir> plugins_doc_caches`
101 NOTE: the newly generated cache should be commited to the git repos.
103 The plugins documentation is generated based on that file to
104 avoid needing to have built all plugins to get the documentation generated.
106 NOTE: When moving plugins from one module to another, the `gst_plugins_cache.json`
107 from the module where the plugin has been removed should be manually edited
108 to reflect the removal.
112 The content of this module comes from a number of different sources and is
113 licensed in different ways:
115 ### Tutorial source code
117 All tutorial code is licensed under any of the following licenses (your choice):
119 - 2-clause BSD license ("simplified BSD license") (`LICENSE.BSD`)
120 - MIT license (`LICENSE.MIT`)
121 - LGPL v2.1 (`LICENSE.LGPL-2.1`), or (at your option) any later version
123 This means developers have maximum flexibility and can pick the right license
124 for any derivative work.
126 ### Application Developer Manual and Plugin Writer's Guide
128 These are licensed under the [Open Publication License v1.0][op-license]
129 (`LICENSE.OPL`), for historical reasons.
131 [op-license]: http://www.opencontent.org/openpub/
137 The tutorials are licensed under the [Creative Commons CC-BY-SA-4.0 license][cc-by-sa-4.0]
138 (`LICENSE.CC-BY-SA-4.0`).
140 [cc-by-sa-4.0]: https://creativecommons.org/licenses/by-sa/4.0/
142 #### API Reference and Design Documentation
144 The remaining documentation, including the API reference and Design Documentation,
145 is licensed under the LGPL v2.1 (`LICENSE.LGPL-2.1`), or (at your option) any later