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
46 [gst-build](https://gitlab.freedesktop.org/gstreamer/gst-build/) which allows us
47 to aggregate the documentation from all GStreamer modules using the hotdoc subproject
54 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 : [gobject_dep, glib_dep, gst_dep, gst_base_dep],
82 install_dir : plugins_install_dir,
84 plugins += [gst_elements]
87 Then when rebuilding, the `gst_plugins_cache.json` file will be updated
88 in the given module and this change should be commited to the git repository.
90 The plugins documentation is generated exclusively based on that file to
91 avoid needing to have built all plugins to get the documentation generated.
93 NOTE: When moving plugins from one module to another, the `gst_plugins_cache.json`
94 from the module where the plugin has been removed should be manually edited
95 to reflect the removal.
99 The content of this module comes from a number of different sources and is
100 licensed in different ways:
102 ### Tutorial source code
104 All tutorial code is licensed under any of the following licenses (your choice):
106 - 2-clause BSD license ("simplified BSD license") (`LICENSE.BSD`)
107 - MIT license (`LICENSE.MIT`)
108 - LGPL v2.1 (`LICENSE.LGPL-2.1`)
110 This means developers have maximum flexibility and can pick the right license
111 for any derivative work.
113 ### Application Developer Manual and Plugin Writer's Guide
115 These are licensed under the [Open Publication License v1.0][op-license]
116 (`LICENSE.OPL`), for historical reasons.
118 [op-license]: http://www.opencontent.org/openpub/
122 Mostly licensed under the [Creative Commons CC-BY-SA-4.0 license][cc-by-sa-4.0],
123 but some parts of the documentation may still be licensed differently
124 (e.g. LGPLv2.1) for historical reasons.
126 [cc-by-sa-4.0]: https://creativecommons.org/licenses/by-sa/4.0/