subprojects/gst-docs/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 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.
  49
  50 From `gstreamer`:
  51
  52 ```
  53 meson build/
  54 ./gst-env 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 : [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 the mono repo build there's also a target that will rebuild all
  95 the cache files in the various GStreamer subprojects:
  96
  97 ```
  98 ninja -C <build-dir> plugins_doc_caches`
  99 ```
 100
 101 NOTE: the newly generated cache should be commited to the git repos.
 102
 103 The plugins documentation is generated based on that file to
 104 avoid needing to have built all plugins to get the documentation generated.
 105
 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.
 109
 110 ## Licensing
 111
 112 The content of this module comes from a number of different sources and is
 113 licensed in different ways:
 114
 115 ### Tutorial source code
 116
 117 All tutorial code is licensed under any of the following licenses (your choice):
 118
 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
 122
 123 This means developers have maximum flexibility and can pick the right license
 124 for any derivative work.
 125
 126 ### Application Developer Manual and Plugin Writer's Guide
 127
 128 These are licensed under the [Open Publication License v1.0][op-license]
 129 (`LICENSE.OPL`), for historical reasons.
 130
 131 [op-license]: http://www.opencontent.org/openpub/
 132
 133 ### Documentation
 134
 135 #### Tutorials
 136
 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`).
 139
 140 [cc-by-sa-4.0]: https://creativecommons.org/licenses/by-sa/4.0/
 141
 142 #### API Reference and Design Documentation
 143
 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
 146 version.