c36c87e47f
Those existing symbols will be newly-documented by hotdoc when updating to a more recent version Part-of: <https://gitlab.freedesktop.org/gstreamer/gst-docs/-/merge_requests/136> |
||
---|---|---|
examples | ||
images | ||
markdown | ||
scripts | ||
symbols | ||
theme/extra | ||
.gitignore | ||
.gitlab-ci.yml | ||
.gitmodules | ||
LICENSE.BSD | ||
LICENSE.CC-BY-SA-4.0 | ||
LICENSE.LGPL-2.1 | ||
LICENSE.MIT | ||
LICENSE.OPL | ||
meson.build | ||
meson_options.txt | ||
README.md | ||
sitemap.txt | ||
TODO.md |
Introduction
This is a collection of design documents, formerly maintained in various different locations and formats, now grouped together and converted to commonmark.
Contributing
Style
We will follow the commonmark specification.
We should try to follow this style guide, but are still evaluating solutions for stable automatic formatting.
80 columns line width is thus not yet enforced, but strongly suggested.
Build the documentation
Install dependencies
-
Follow hotdoc's installation guide, preferably in a virtualenv.
-
We experimentally use the hotdoc C extension to include functions by name, follow the steps outlined here
Build the portal without the API documentation
meson build
ninja -C build/ GStreamer-doc
And browse it:
gio open build/GStreamer-doc/html/index.html
API documentation
Building the API documentation in the portal implies using gst-build which allows us to aggregate the documentation from all GStreamer modules using the hotdoc subproject feature.
From gst-build
:
meson build/
ninja -C build subprojects/gst-docs/GStreamer-doc
And browse the doc:
gio open build/subprojects/gst-docs/GStreamer-doc/html/index.html
You can also generate a release tarball of the portal with:
ninja -C build gst-docs@@release
Adding a newly written plugin to the documentation
To add a plugin to the documentation you need to add the given
meson target to the plugins
list present in each GStreamer module for
example:
gst_elements = library('gstcoreelements',
gst_elements_sources,
c_args : gst_c_args,
include_directories : [configinc],
dependencies : [gobject_dep, glib_dep, gst_dep, gst_base_dep],
install : true,
install_dir : plugins_install_dir,
)
plugins += [gst_elements]
Then you need to regenerate the gst_plugins_cache.json
file by running
the target manually, if building from the module itself:
ninja -C <build-dir> docs/gst_plugins_cache.json
if you use gst-build
you can run the target that will rebuild all cache files:
ninja -C <build-dir> plugins_doc_caches`
NOTE: the newly generated cache should be commited to the git repos.
The plugins documentation is generated based on that file to avoid needing to have built all plugins to get the documentation generated.
NOTE: When moving plugins from one module to another, the gst_plugins_cache.json
from the module where the plugin has been removed should be manually edited
to reflect the removal.
Licensing
The content of this module comes from a number of different sources and is licensed in different ways:
Tutorial source code
All tutorial code is licensed under any of the following licenses (your choice):
- 2-clause BSD license ("simplified BSD license") (
LICENSE.BSD
) - MIT license (
LICENSE.MIT
) - LGPL v2.1 (
LICENSE.LGPL-2.1
), or (at your option) any later version
This means developers have maximum flexibility and can pick the right license for any derivative work.
Application Developer Manual and Plugin Writer's Guide
These are licensed under the Open Publication License v1.0
(LICENSE.OPL
), for historical reasons.
Documentation
Tutorials
The tutorials are licensed under the Creative Commons CC-BY-SA-4.0 license
(LICENSE.CC-BY-SA-4.0
).
API Reference and Design Documentation
The remaining documentation, including the API reference and Design Documentation,
is licensed under the LGPL v2.1 (LICENSE.LGPL-2.1
), or (at your option) any later
version.