README.md 3.66 KB
Newer Older
Mathieu Duponchelle's avatar
Mathieu Duponchelle committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# Introduction

This is a collection of design documents, formerly maintained in various
different locations and formats, now grouped together and converted
to commonmark.

# Contributing

## Style

We will follow the commonmark specification.

We *should* try to follow this
[style guide](http://www.cirosantilli.com/markdown-style-guide/#about),
but are still [evaluating solutions](https://github.com/jgm/cmark/issues/131)
for *stable* automatic formatting.

80 columns line width is thus not yet enforced, but strongly suggested.

20
# Build the documentation
Mathieu Duponchelle's avatar
Mathieu Duponchelle committed
21
22
23

## Install dependencies

24
* Follow [hotdoc's installation guide](https://hotdoc.github.io/installing.html),
Mathieu Duponchelle's avatar
Mathieu Duponchelle committed
25
26
  preferably in a virtualenv.

27
28
29
* We *experimentally* use the hotdoc C extension to include functions by
  name, follow the steps outlined [here](https://github.com/hotdoc/hotdoc_c_extension)

30
## Build the portal without the API documentation
Mathieu Duponchelle's avatar
Mathieu Duponchelle committed
31
32

```
33
34
meson build
ninja -C build/ GStreamer-doc
Mathieu Duponchelle's avatar
Mathieu Duponchelle committed
35
36
```

37
And browse it:
Mathieu Duponchelle's avatar
Mathieu Duponchelle committed
38
39

```
40
gio open build/GStreamer-doc/html/index.html
Mathieu Duponchelle's avatar
Mathieu Duponchelle committed
41
```
42

43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
## API documentation

Building the API documentation in the portal implies using
[gst-build](https://gitlab.freedesktop.org/gstreamer/gst-build/) which allows us
to aggregate the documentation from all GStreamer modules using the hotdoc subproject
feature.

From `gst-build`:

```
meson build/
ninja -C build subprojects/gst-docs/GStreamer-doc
```

And browse the doc:

```
gio open build/subprojects/gst-docs/GStreamer-doc/html/index.html
```

You can also generate a release tarball of the portal with:

```
66
ninja -C build gst-docs@@release
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
```

### Adding a newly written plugin to the documentation

To add a plugin to the documentation you need to add the given
meson target to the `plugins` list present in each GStreamer module for
example:

``` meson
gst_elements = library('gstcoreelements',
  gst_elements_sources,
  c_args : gst_c_args,
  include_directories : [configinc],
  dependencies : [gobject_dep, glib_dep, gst_dep, gst_base_dep],
  install : true,
  install_dir : plugins_install_dir,
)
plugins += [gst_elements]
```

87
88
Then you need to regenerate the `gst_plugins_cache.json` file by running
the target manually, if building from the module itself:
89

90
91
92
93
94
95
96
97
98
99
100
101
102
```
ninja -C <build-dir> docs/gst_plugins_cache.json
```

if you use `gst-build` you can run the target that will rebuild all cache files:

```
ninja -C <build-dir> plugins_doc_caches`
```

NOTE: the newly generated cache should be commited to the git repos.

The plugins documentation is generated based on that file to
103
104
105
106
107
108
avoid needing to have built all plugins to get the documentation generated.

NOTE: When moving plugins from one module to another, the `gst_plugins_cache.json`
from the module where the plugin has been removed should be manually edited
to reflect the removal.

109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
## Licensing

The content of this module comes from a number of different sources and is
licensed in different ways:

### Tutorial source code

All tutorial code is licensed under any of the following licenses (your choice):

 - 2-clause BSD license ("simplified BSD license") (`LICENSE.BSD`)
 - MIT license (`LICENSE.MIT`)
 - LGPL v2.1 (`LICENSE.LGPL-2.1`)

This means developers have maximum flexibility and can pick the right license
for any derivative work.

### Application Developer Manual and Plugin Writer's Guide

These are licensed under the [Open Publication License v1.0][op-license]
(`LICENSE.OPL`), for historical reasons.

[op-license]: http://www.opencontent.org/openpub/

### Documentation

Mostly licensed under the [Creative Commons CC-BY-SA-4.0 license][cc-by-sa-4.0],
but some parts of the documentation may still be licensed differently
(e.g. LGPLv2.1) for historical reasons.

[cc-by-sa-4.0]: https://creativecommons.org/licenses/by-sa/4.0/