144 lines
5.2 KiB
Plaintext
144 lines
5.2 KiB
Plaintext
GStreamer documentation notes
|
|
|
|
OVERVIEW
|
|
========
|
|
|
|
Our documentation uses hotdoc, you should usually refer to the
|
|
[hotdoc documentation](http://hotdoc.github.io/).
|
|
|
|
GStreamer has two sets of documentation but both are controlled and aggregated in
|
|
the `gst-docs` module:
|
|
|
|
* API references, using hotdoc (gstreamer, gstreamer-libs) - maintained
|
|
in each GStreamer modules repository
|
|
* FAQ / Application Development Manual / Plugin Writer's Guide / Tutorials -
|
|
these are maintained in markdown format and live in the gst-docs repository.
|
|
|
|
To build the full documentation you should make sure to have `hotdoc` installed and
|
|
build [gst-build](https://cgit.freedesktop.org/gstreamer/gst-build/) configuring it with:
|
|
|
|
```
|
|
meson -Ddoc=enabled build/
|
|
```
|
|
|
|
And building the documentation:
|
|
|
|
```
|
|
ninja -C build/ subprojects/gst-docs/GStreamer-doc`, this will result in two documentation sets:
|
|
```
|
|
|
|
This will generate two outputs:
|
|
|
|
- the html in `build/subprojects/gst-docs/GStreamer-doc/html`
|
|
- the [devhelp](https://wiki.gnome.org/Apps/Devhelp) in `build/subprojects/gst-docs/GStreamer-doc/devhelp`
|
|
|
|
HOW THE BUILD SYSTEM IS SET UP
|
|
------------------------------
|
|
Hotdoc build targets are generated for each documentation 'components' (ie. hotdoc
|
|
subprojects). This includes libraries documentation and one target per GStreamer plugin.
|
|
|
|
One can build a specific documentation target by explicitly building the target,
|
|
for example to build the GStreamer core library documentation (adapt the paths if you
|
|
are using `gst-build`):
|
|
|
|
ninja docs/libgstreamer-doc
|
|
|
|
Then the documentation will be available in `docs/libgstreamer-doc/html/`.
|
|
|
|
SPELL CHECKING
|
|
--------------
|
|
|
|
FILL ME.
|
|
|
|
HOTDOC NOTES
|
|
=============
|
|
|
|
* files under revision control:
|
|
- sitemap.txt: defines the overall structure of the documentation
|
|
- gst_plugins_cache.json: Automatically generated information about plugins
|
|
|
|
* what to do when adding a new piece of API:
|
|
- Just let hotdoc generate the documentation and decide where to put it
|
|
- Make sure to add a `SECTION` documentation section in the file where
|
|
the documentation should land (hotdoc will use that to create its
|
|
"smart index" and list symbols from other files that should land
|
|
on that page in that section.
|
|
- document functions, signals in the .c files
|
|
- document structs, typedefs, enums in the .h files
|
|
|
|
* what to do when trying to improve the docs
|
|
- compare the output of
|
|
grep "_get_type" gstreamer-sections.txt | sort
|
|
with the types in XXX.types to detect entries that
|
|
are maybe missing
|
|
- hotdoc does not warns about empty member docs!, run
|
|
find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@.*: *$" {} \;
|
|
in the project root to find them
|
|
- hotdoc does not warns about empty Returns: docs!, run
|
|
find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@Returns: *$" {} \;
|
|
in the project root to find them
|
|
|
|
* what happens during a hotdoc build ?
|
|
- Read the GIR and scan the sources files for the docstrings and
|
|
generate the documentation laying out pages the way they are documented.
|
|
- The meson build definition is set in a way that makes it so all plugins
|
|
in `plugins_doc` are introspected and documented
|
|
|
|
STYLE GUIDE FOR HOTDOC
|
|
=======================
|
|
- this is in addition to gtk-doc's style-guide.txt
|
|
|
|
- function/macro descriptions are descriptive, not imperative
|
|
ie, it uses the third person verb
|
|
- synopsis and description should have most-used/application functions at the
|
|
top
|
|
- functions that can return FALSE/NULL or fail should describe their failure
|
|
conditions like this:
|
|
* Returns NULL if no element with the given name is found in the bin, if
|
|
* the frobble was stuck in the froob, or the frizzle was frazzed.
|
|
- a line with function attributes should be added before Returns:
|
|
- can contain:
|
|
"MT safe." - the function is verified to be multithreadingsafe
|
|
"Caller owns returned reference" for refcounted classes
|
|
"Caller owns returned value" for other types (iterators, ..)
|
|
- we do this because, in contrast with GLib/GTK, we are more explicit
|
|
about threadsafety and related issues
|
|
|
|
WEBSITE DOCUMENTATION
|
|
=====================
|
|
|
|
Updating the online documentation is done from with the `gst-docs` repository
|
|
|
|
DOCUMENTING ELEMENTS
|
|
====================
|
|
A hotdoc plugin is provided by GStreamer to document GStreamer plugins.
|
|
|
|
- to add a plugin to be documented:
|
|
- make sure the plugin is added to the `plugins_doc` variable in meson
|
|
- to add an element to be documented:
|
|
- add a gtk-doc section to the source code like:
|
|
/**
|
|
* SECTION:element-multifdsink
|
|
|
|
and fill it with documentation about the element
|
|
- add an example:
|
|
- either a few pipelines, inside a codeblock
|
|
- or a piece of code inside a codeblock or in `tests/examples/(pluginname)`
|
|
- to build the doc for a plugin, do:
|
|
`ninja docs/(pluginname)-doc`
|
|
|
|
|
|
DEVHELP INTEGRATION
|
|
-------------------
|
|
Check https://wiki.gnome.org/Apps/Devhelp
|
|
It's a really nice development app allowing you to look up API stuff
|
|
from various hotdoc/gtk-doc'd libraries. GStreamer is one of these ;)
|
|
|
|
hotdoc generates both html API docs and the matching .devhelp(2) books.
|
|
|
|
IMAGES
|
|
------
|
|
It's important to keep the original source format for images, to be able
|
|
to change and regenerate later on. Original files go in
|
|
docs/images
|