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 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.
  89
  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.
  92
  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.
  96
  97 ## Licensing
  98
  99 The content of this module comes from a number of different sources and is
 100 licensed in different ways:
 101
 102 ### Tutorial source code
 103
 104 All tutorial code is licensed under any of the following licenses (your choice):
 105
 106  - 2-clause BSD license ("simplified BSD license") (`LICENSE.BSD`)
 107  - MIT license (`LICENSE.MIT`)
 108  - LGPL v2.1 (`LICENSE.LGPL-2.1`)
 109
 110 This means developers have maximum flexibility and can pick the right license
 111 for any derivative work.
 112
 113 ### Application Developer Manual and Plugin Writer's Guide
 114
 115 These are licensed under the [Open Publication License v1.0][op-license]
 116 (`LICENSE.OPL`), for historical reasons.
 117
 118 [op-license]: http://www.opencontent.org/openpub/
 119
 120 ### Documentation
 121
 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.
 125
 126 [cc-by-sa-4.0]: https://creativecommons.org/licenses/by-sa/4.0/