subprojects/gstreamer/docs/README

   1 GStreamer documentation notes
   2
   3 OVERVIEW
   4 ========
   5
   6 Our documentation uses hotdoc, you should usually refer to the
   7 [hotdoc documentation](http://hotdoc.github.io/).
   8
   9 GStreamer has two sets of documentation but both are controlled and aggregated in
  10 the `gst-docs` module:
  11
  12 * API references, using hotdoc (gstreamer, gstreamer-libs) - maintained
  13   in each GStreamer modules repository
  14 * FAQ / Application Development Manual / Plugin Writer's Guide / Tutorials -
  15   these are maintained in markdown format and live in the gst-docs repository.
  16
  17 To build the full documentation you should make sure to have `hotdoc` installed and
  18 build [gst-build](https://cgit.freedesktop.org/gstreamer/gst-build/) configuring it with:
  19
  20 ```
  21 meson -Ddoc=enabled build/
  22 ```
  23
  24 And building the documentation:
  25
  26 ```
  27 ninja -C build/ subprojects/gst-docs/GStreamer-doc`, this will result in two documentation sets:
  28 ```
  29
  30 This will generate two outputs:
  31
  32   - the html in `build/subprojects/gst-docs/GStreamer-doc/html`
  33   - the [devhelp](https://wiki.gnome.org/Apps/Devhelp) in `build/subprojects/gst-docs/GStreamer-doc/devhelp`
  34
  35 HOW THE BUILD SYSTEM IS SET UP
  36 ------------------------------
  37 Hotdoc build targets are generated for each documentation 'components' (ie. hotdoc
  38 subprojects). This includes libraries documentation and one target per GStreamer plugin.
  39
  40 One can build a specific documentation target by explicitly building the target,
  41 for example to build the GStreamer core library documentation (adapt the paths if you
  42 are using `gst-build`):
  43
  44     ninja docs/libgstreamer-doc
  45
  46 Then the documentation will be available in `docs/libgstreamer-doc/html/`.
  47
  48 SPELL CHECKING
  49 --------------
  50
  51 FILL ME.
  52
  53 HOTDOC NOTES
  54 =============
  55
  56 * files under revision control:
  57   - sitemap.txt: defines the overall structure of the documentation
  58   - gst_plugins_cache.json: Automatically generated information about plugins
  59
  60 * what to do when adding a new piece of API:
  61   - Just let hotdoc generate the documentation and decide where to put it
  62   - Make sure to add a `SECTION` documentation section in the file where
  63     the documentation should land (hotdoc will use that to create its
  64     "smart index" and list symbols from other files that should land
  65     on that page in that section.
  66   - document functions, signals in the .c files
  67   - document structs, typedefs, enums in the .h files
  68
  69 * what to do when trying to improve the docs
  70   - compare the output of
  71     grep "_get_type" gstreamer-sections.txt | sort
  72     with the types in XXX.types to detect entries that
  73     are maybe missing
  74   - hotdoc does not warns about empty member docs!, run
  75     find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@.*: *$" {} \;
  76     in the project root to find them
  77   - hotdoc does not warns about empty Returns: docs!, run
  78     find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@Returns: *$" {} \;
  79     in the project root to find them
  80
  81 * what happens during a hotdoc build ?
  82   - Read the GIR and scan the sources files for the docstrings and
  83     generate the documentation laying out pages the way they are documented.
  84   - The meson build definition is set in a way that makes it so all plugins
  85     in `plugins_doc` are introspected and documented
  86
  87 STYLE GUIDE FOR HOTDOC
  88 =======================
  89 - this is in addition to gtk-doc's style-guide.txt
  90
  91 - function/macro descriptions are descriptive, not imperative
  92   ie, it uses the third person verb
  93 - synopsis and description should have most-used/application functions at the
  94   top
  95 - functions that can return FALSE/NULL or fail should describe their failure
  96   conditions like this:
  97   * Returns NULL if no element with the given name is found in the bin, if
  98   * the frobble was stuck in the froob, or the frizzle was frazzed.
  99 - a line with function attributes should be added before Returns:
 100   - can contain:
 101     "MT safe." - the function is verified to be multithreadingsafe
 102     "Caller owns returned reference" for refcounted classes
 103     "Caller owns returned value" for other types (iterators, ..)
 104   - we do this because, in contrast with GLib/GTK, we are more explicit
 105     about threadsafety and related issues
 106
 107 WEBSITE DOCUMENTATION
 108 =====================
 109
 110 Updating the online documentation is done from with the `gst-docs` repository
 111
 112 DOCUMENTING ELEMENTS
 113 ====================
 114 A hotdoc plugin is provided by GStreamer to document GStreamer plugins.
 115
 116 - to add a plugin to be documented:
 117   - make sure the plugin is added to the `plugins_doc` variable in meson
 118 - to add an element to be documented:
 119   - add a gtk-doc section to the source code like:
 120 /**
 121  * SECTION:element-multifdsink
 122
 123   and fill it with documentation about the element
 124   - add an example:
 125     - either a few pipelines, inside a codeblock
 126     - or a piece of code inside a codeblock or in `tests/examples/(pluginname)`
 127   - to build the doc for a plugin, do:
 128     `ninja docs/(pluginname)-doc`
 129
 130
 131 DEVHELP INTEGRATION
 132 -------------------
 133 Check https://wiki.gnome.org/Apps/Devhelp
 134 It's a really nice development app allowing you to look up API stuff
 135 from various hotdoc/gtk-doc'd libraries.  GStreamer is one of these ;)
 136
 137 hotdoc generates both html API docs and the matching .devhelp(2) books.
 138
 139 IMAGES
 140 ------
 141 It's important to keep the original source format for images, to be able
 142 to change and regenerate later on.  Original files go in
 143 docs/images