Commit 185e2d8a authored by Thibault Saunier's avatar Thibault Saunier 🌵

Merging gst-docs

parents 6cf69ffa bb763528
/built_doc
/hotdoc-private*
/.hotdoc.d
/*.stamp
Debug
Release
ipch
*.user
*.sdf
*.suo
*.opensdf
vs/2010/libs
bin
gen
libs
obj
.classpath
.project
.settings
.libs
.cproject
gst-build
project.properties
gst_sdk
.DS_Store
xcuserdata
/plugins-introspection/cache/
/hotdoc_env/
*.html
*~
include: 'https://gitlab.freedesktop.org/gstreamer/gst-ci/raw/master/gitlab/ci_template.yml'
Copyright (C) GStreamer developers
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
This diff is collapsed.
This diff is collapsed.
Copyright (C) GStreamer developers
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
Open Publication License
v1.0, 8 June 1999
I. REQUIREMENTS ON BOTH UNMODIFIED AND MODIFIED VERSIONS
The Open Publication works may be reproduced and distributed in whole or in
part, in any medium physical or electronic, provided that the terms of this
license are adhered to, and that this license or an incorporation of it by
reference (with any options elected by the author(s) and/or publisher) is
displayed in the reproduction.
Proper form for an incorporation by reference is as follows:
Copyright (c) <year> by <author's name or designee>. This material
may be distributed only subject to the terms and conditions set
forth in the Open Publication License, vX.Y or later (the latest
version is presently available at http://www.opencontent.org/openpub/).
The reference must be immediately followed with any options elected by the
author(s) and/or publisher of the document (see section VI).
Commercial redistribution of Open Publication-licensed material is permitted.
Any publication in standard (paper) book form shall require the citation of
the original publisher and author. The publisher and author's names shall
appear on all outer surfaces of the book. On all outer surfaces of the book
the original publisher's name shall be as large as the title of the work
and cited as possessive with respect to the title.
II. COPYRIGHT
The copyright to each Open Publication is owned by its author(s) or designee.
III. SCOPE OF LICENSE
The following license terms apply to all Open Publication works, unless
otherwise explicitly stated in the document.
Mere aggregation of Open Publication works or a portion of an Open Publication
work with other works or programs on the same media shall not cause this
license to apply to those other works. The aggregate work shall contain a
notice specifying the inclusion of the Open Publication material and
appropriate copyright notice.
SEVERABILITY. If any part of this license is found to be unenforceable in any
jurisdiction, the remaining portions of the license remain in force.
NO WARRANTY. Open Publication works are licensed and provided "as is" without
warranty of any kind, express or implied, including, but not limited to, the
implied warranties of merchantability and fitness for a particular purpose or
a warranty of non-infringement.
IV. REQUIREMENTS ON MODIFIED WORKS
All modified versions of documents covered by this license, including
translations, anthologies, compilations and partial documents, must meet
the following requirements:
1. The modified version must be labeled as such.
2. The person making the modifications must be identified and the
modifications dated.
3. Acknowledgement of the original author and publisher if applicable
must be retained according to normal academic citation practices.
4. The location of the original unmodified document must be identified.
5. The original author's (or authors') name(s) may not be used to assert
or imply endorsement of the resulting document without the original
author's (or authors') permission.
V. GOOD-PRACTICE RECOMMENDATIONS
In addition to the requirements of this license, it is requested from and
strongly recommended of redistributors that:
1. If you are distributing Open Publication works on hardcopy or CD-ROM,
you provide email notification to the authors of your intent to
redistribute at least thirty days before your manuscript or media freeze,
to give the authors time to provide updated documents. This notification
should describe modifications, if any, made to the document.
2. All substantive modifications (including deletions) be either clearly
marked up in the document or else described in an attachment to the
document.
3. Finally, while it is not mandatory under this license, it is considered
good form to offer a free copy of any hardcopy and CD-ROM expression of
an Open Publication-licensed work to its author(s).
VI. LICENSE OPTIONS
The author(s) and/or publisher of an Open Publication-licensed document may
elect certain options by appending language to the reference to or copy of the
license. These options are considered part of the license instance and must be
included with the license (or its incorporation by reference) in derived works.
A. To prohibit distribution of substantively modified versions without the
explicit permission of the author(s). "Substantive modification" is defined
as a change to the semantic content of the document, and excludes mere changes
in format or typographical corrections.
To accomplish this, add the phrase `Distribution of substantively modified
versions of this document is prohibited without the explicit permission of
the copyright holder.' to the license reference or copy.
B. To prohibit any publication of this work or derivative works in whole or
in part in standard (paper) book form for commercial purposes is prohibited
unless prior permission is obtained from the copyright holder.
To accomplish this, add the phrase 'Distribution of the work or derivative of
the work in any standard (paper) book form is prohibited unless prior
permission is obtained from the copyright holder.' to the license reference
or copy.
OPEN PUBLICATION POLICY APPENDIX:
(This is not considered part of the license.)
Open Publication works are available in source format via the Open Publication
home page at http://works.opencontent.org/.
Open Publication authors who want to include their own license on Open
Publication works may do so, as long as their terms are not more restrictive
than the Open Publication license.
If you have questions about the Open Publication License, please contact
David Wiley, and/or the Open Publication Authors' List at opal@opencontent.org,
via email.
# 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](http://www.cirosantilli.com/markdown-style-guide/#about),
but are still [evaluating solutions](https://github.com/jgm/cmark/issues/131)
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](https://hotdoc.github.io/installing.html),
preferably in a virtualenv.
* We *experimentally* use the hotdoc C extension to include functions by
name, follow the steps outlined [here](https://github.com/hotdoc/hotdoc_c_extension)
## 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](https://gitlab.freedesktop.org/gstreamer/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:
``` meson
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][op-license]
(`LICENSE.OPL`), for historical reasons.
[op-license]: http://www.opencontent.org/openpub/
### Documentation
Mostly licensed under the [Creative Commons CC-BY-SA-4.0 license][cc-by-sa-4.0],
but some parts of the documentation may still be licensed differently
(e.g. LGPLv2.1) for historical reasons.
[cc-by-sa-4.0]: https://creativecommons.org/licenses/by-sa/4.0/
# Todo
For-later pages:
- tutorials/qt-tutorials.md [tpm: this should all be rewritten from scratch with qmlglsink; QtGStreamer is outdated and unmaintained, we should not promote it]
- basic-media-player.md
- qt-gstreamer-vs-c-gstreamer.md
- using-appsink-appsrc-in-qt.md
Miscellaneous:
- faq/git.md should be renamed building.md and turned into general
building Q+A or (better) point to a page we have for all that by then
- faq/legal.md needs an overhaul, and be made more relevant
- licensing.md and legal-information.md need to be reviewed + merged,
possibly with FAQ section.
old sitemap:
Installing the SDK
Installing on Linux
Installing on Mac OS X
Installing on Windows
Installing for Android development
Installing for iOS development
Building from source using Cerbero
Tutorials
Basic tutorials
Playback tutorials
Android tutorials
iOS tutorials
Table of Concepts
Upcoming tutorials
Deploying your application
Mac OS X deployment
Windows deployment
Multiplatform deployment using Cerbero
GStreamer reference
gst-inspect