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
  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`), or (at your option) any later version
 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 #### Tutorials
 135
 136 The tutorials are licensed under the [Creative Commons CC-BY-SA-4.0 license][cc-by-sa-4.0]
 137 (`LICENSE.CC-BY-SA-4.0`).
 138
 139 [cc-by-sa-4.0]: https://creativecommons.org/licenses/by-sa/4.0/
 140
 141 #### API Reference and Design Documentation
 142
 143 The remaining documentation, including the API reference and Design Documentation,
 144 is licensed under the LGPL v2.1 (`LICENSE.LGPL-2.1`), or (at your option) any later
 145 version.