GStreamer multimedia framework
Find a file
Edward Hervey 7dd3be2d49 FAQ/developing: Point directly to "developing with meson" docs
Instead of repeating old stuff also :) And ensures everything is centralized in
on doc.

Partly fixes #54

Part-of: <https://gitlab.freedesktop.org/gstreamer/gst-docs/-/merge_requests/90>
2020-05-12 16:21:14 +02:00
examples Cerbero has moved from gnutls+openssl to only openssl 2020-03-02 16:38:17 +05:30
images Build GStreamer modules API documentation as part of our build 2019-05-13 11:39:10 -04:00
markdown FAQ/developing: Point directly to "developing with meson" docs 2020-05-12 16:21:14 +02:00
scripts Heavily refactor the sitemap 2019-05-30 02:55:43 +02:00
theme/extra navbar: Fix link to GStreamer core lib 2019-05-31 23:45:20 -04:00
.gitignore .gitignore: Adds HTML and backup files 2019-05-03 16:21:49 +02:00
.gitlab-ci.yml gitlab: Use the standard gst-ci definition 2019-05-13 17:00:00 -04:00
.gitmodules Use official hotdoc_lumen_theme instead of building it ourselves 2018-08-27 15:28:26 -03:00
LICENSE.BSD Add licensing information 2018-05-31 21:15:42 +01:00
LICENSE.CC-BY-SA-4.0 Add licensing information 2018-05-31 21:15:42 +01:00
LICENSE.LGPL-2.1 Add licensing information 2018-05-31 21:15:42 +01:00
LICENSE.MIT Add licensing information 2018-05-31 21:15:42 +01:00
LICENSE.OPL Add licensing information 2018-05-31 21:15:42 +01:00
meson.build build: also read the subproject list from a generated file 2020-04-23 13:51:03 +10:00
meson_options.txt Build GStreamer modules API documentation as part of our build 2019-05-13 11:39:10 -04:00
README.md Update the readme now that plugins doc cache is manually built 2019-05-16 14:01:01 -04:00
sitemap.txt Add meson/gst-build instructions 2020-05-12 15:24:16 +02:00
TODO.md Move licensing page over from www module 2016-11-29 10:28:14 +00: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 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)

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

Mostly licensed under the Creative Commons CC-BY-SA-4.0 license, but some parts of the documentation may still be licensed differently (e.g. LGPLv2.1) for historical reasons.