gstreamer/subprojects/gst-docs
Jordan Petridis 7d64943b9d docs: Remove obselete appendix about parsing cli argumnets
It's a bad idea trying to mix the Options from GStramer and
GTK, in addition with cli argument being a bit wonky thing for
GUI applications in general. In the rare, now, occasion
that an application wants to parse arguments, its preferable
to parse them manually and use library apis afterwards
rather than trying to combine the option groups and hope it
works.

In addition, applications should be opening files using
`g_application_open` instead of parsing random arguments.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/4788>
2023-10-27 04:46:17 +00:00
..
examples examples: update ios deplyoment target to 12.0 2023-07-27 13:05:37 +00:00
images docs: Explain how to open a merge request with screenshots 2022-01-27 10:11:51 +05:30
markdown docs: Remove obselete appendix about parsing cli argumnets 2023-10-27 04:46:17 +00:00
scripts gst-omx: Retire the whole package 2023-07-16 19:10:03 +00:00
symbols symbol_index: Add ladspa-ladspa-rubberband-so-rubberband-pitchshifter 2023-10-22 05:23:29 +03:00
theme/extra gst-docs: add higher-resolution favicons 2023-08-01 02:23:17 +00:00
.gitignore Move files from gst-docs into the "subprojects/gst-docs/" subdir 2021-09-24 16:15:51 -03:00
.gitmodules Move files from gst-docs into the "subprojects/gst-docs/" subdir 2021-09-24 16:15:51 -03:00
LICENSE.BSD Move files from gst-docs into the "subprojects/gst-docs/" subdir 2021-09-24 16:15:51 -03:00
LICENSE.CC-BY-SA-4.0 Move files from gst-docs into the "subprojects/gst-docs/" subdir 2021-09-24 16:15:51 -03:00
LICENSE.LGPL-2.1 Move files from gst-docs into the "subprojects/gst-docs/" subdir 2021-09-24 16:15:51 -03:00
LICENSE.MIT Move files from gst-docs into the "subprojects/gst-docs/" subdir 2021-09-24 16:15:51 -03:00
LICENSE.OPL Move files from gst-docs into the "subprojects/gst-docs/" subdir 2021-09-24 16:15:51 -03:00
meson.build docs: update hotdoc theme to 0.15 2023-04-26 13:50:42 +02:00
meson_options.txt doc: Add an option to enable fatal warnings 2022-09-15 20:11:46 +00:00
README.md Remove glib and gobject dependencies everywhere 2022-04-01 16:32:17 +00:00
sitemap.txt gst-docs: include dmabuf and gapless playback design docs 2023-01-18 13:48:14 +00:00
TODO.md Move files from gst-docs into the "subprojects/gst-docs/" subdir 2021-09-24 16:15:51 -03:00

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 the full multi-repo gstreamer build which allows us to aggregate the documentation from all GStreamer modules using the hotdoc subproject feature.

From gstreamer:

meson build/
./gst-env 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 : [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 the mono repo build there's also a target that will rebuild all the cache files in the various GStreamer subprojects:

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.