Update the readme now that plugins doc cache is manually built
[platform/upstream/gstreamer.git] / README.md
1 # Introduction
2
3 This is a collection of design documents, formerly maintained in various
4 different locations and formats, now grouped together and converted
5 to commonmark.
6
7 # Contributing
8
9 ## Style
10
11 We will follow the commonmark specification.
12
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.
17
18 80 columns line width is thus not yet enforced, but strongly suggested.
19
20 # Build the documentation
21
22 ## Install dependencies
23
24 * Follow [hotdoc's installation guide](https://hotdoc.github.io/installing.html),
25   preferably in a virtualenv.
26
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)
29
30 ## Build the portal without the API documentation
31
32 ```
33 meson build
34 ninja -C build/ GStreamer-doc
35 ```
36
37 And browse it:
38
39 ```
40 gio open build/GStreamer-doc/html/index.html
41 ```
42
43 ## API documentation
44
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
48 feature.
49
50 From `gst-build`:
51
52 ```
53 meson build/
54 ninja -C build subprojects/gst-docs/GStreamer-doc
55 ```
56
57 And browse the doc:
58
59 ```
60 gio open build/subprojects/gst-docs/GStreamer-doc/html/index.html
61 ```
62
63 You can also generate a release tarball of the portal with:
64
65 ```
66 ninja -C build gst-docs@release
67 ```
68
69 ### Adding a newly written plugin to the documentation
70
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
73 example:
74
75 ``` meson
76 gst_elements = library('gstcoreelements',
77   gst_elements_sources,
78   c_args : gst_c_args,
79   include_directories : [configinc],
80   dependencies : [gobject_dep, glib_dep, gst_dep, gst_base_dep],
81   install : true,
82   install_dir : plugins_install_dir,
83 )
84 plugins += [gst_elements]
85 ```
86
87 Then you need to regenerate the `gst_plugins_cache.json` file by running
88 the target manually, if building from the module itself:
89
90 ```
91 ninja -C <build-dir> docs/gst_plugins_cache.json
92 ```
93
94 if you use `gst-build` you can run the target that will rebuild all cache files:
95
96 ```
97 ninja -C <build-dir> plugins_doc_caches`
98 ```
99
100 NOTE: the newly generated cache should be commited to the git repos.
101
102 The plugins documentation is generated based on that file to
103 avoid needing to have built all plugins to get the documentation generated.
104
105 NOTE: When moving plugins from one module to another, the `gst_plugins_cache.json`
106 from the module where the plugin has been removed should be manually edited
107 to reflect the removal.
108
109 ## Licensing
110
111 The content of this module comes from a number of different sources and is
112 licensed in different ways:
113
114 ### Tutorial source code
115
116 All tutorial code is licensed under any of the following licenses (your choice):
117
118  - 2-clause BSD license ("simplified BSD license") (`LICENSE.BSD`)
119  - MIT license (`LICENSE.MIT`)
120  - LGPL v2.1 (`LICENSE.LGPL-2.1`)
121
122 This means developers have maximum flexibility and can pick the right license
123 for any derivative work.
124
125 ### Application Developer Manual and Plugin Writer's Guide
126
127 These are licensed under the [Open Publication License v1.0][op-license]
128 (`LICENSE.OPL`), for historical reasons.
129
130 [op-license]: http://www.opencontent.org/openpub/
131
132 ### Documentation
133
134 Mostly licensed under the [Creative Commons CC-BY-SA-4.0 license][cc-by-sa-4.0],
135 but some parts of the documentation may still be licensed differently
136 (e.g. LGPLv2.1) for historical reasons.
137
138 [cc-by-sa-4.0]: https://creativecommons.org/licenses/by-sa/4.0/