mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-23 18:21:04 +00:00
285 lines
11 KiB
Text
285 lines
11 KiB
Text
GStreamer documentation notes
|
|
|
|
IMPORTANT
|
|
=========
|
|
|
|
Please make sure you've read and understood everything in this file
|
|
before you try changing documentation.
|
|
|
|
OVERVIEW
|
|
========
|
|
|
|
GStreamer has two sets of documentation that we maintain:
|
|
* API references, using gtk-doc (gstreamer, gstreamer-libs)
|
|
* "books", using DocBook/XML (faq, manual, pwg)
|
|
|
|
DOCBOOK NOTES
|
|
=============
|
|
|
|
OK, I've grown so tired of having to coax the docs to build every time I
|
|
get round to it that I've decided to note down some of the things that
|
|
are important to know.
|
|
|
|
OVERVIEW
|
|
--------
|
|
* Our documentation should all be Docbook/XML. No SGML.
|
|
* The source for the documentation is:
|
|
- one or more .xml files, with the main one being gstreamer-(whatever).xml
|
|
- image files
|
|
- in .fig
|
|
- in .png (and maybe others)
|
|
* We want to generate docs in HTML, PS and PDF
|
|
* We want to use xml to to generate these
|
|
|
|
CONVENTIONS
|
|
-----------
|
|
We stick to some simple conventions for writing docbook documentation.
|
|
* id names:
|
|
- all id's start with chapter-, part-, section-, or misc-
|
|
- verify this is the case by looking at the generated file names in html/
|
|
- sections should also include the chapter name;
|
|
for example in a chapter called chapter-example, a section would be
|
|
called section-example-hello-world
|
|
|
|
HOW IMAGES ARE HANDLED
|
|
----------------------
|
|
* the format of images used is:
|
|
- PNG for html
|
|
- EPS for ps
|
|
- PDF for pdf
|
|
|
|
* images may need to be converted from their source format to the end format
|
|
|
|
* a file called image.entities is generated that provides two entities:
|
|
ℑ and ℑ
|
|
ℑ is the file extension (png, ps, pdf)
|
|
* all generated images will be put in images/
|
|
|
|
HOW THE BUILD WORKS FOR EACH FORMAT
|
|
-----------------------------------
|
|
* HTML:
|
|
- xmlto html gstreamer-whatever.xml should produce the html docs.
|
|
- We do this in the html subdir of the doc builddir.
|
|
- images are copied to (builddir)/html/images
|
|
- PNGS should be set to all of the png's referenced for html, both
|
|
already there and auto-generated
|
|
|
|
* PS :
|
|
- images are converted to .ps files in EPS format. Generated images are
|
|
put in images/
|
|
- xmlto ps gstreamer-whatever.xml generates the ps file
|
|
|
|
* PDF :
|
|
There are two ways:
|
|
- ps2pdf is the easiest
|
|
- we specify ps, PS as the image type, but using xmlto the build will fail
|
|
because it uses ps2pdf internally and it fails to generate the images
|
|
By hand-generating .pdf images before xmlto we can make the build succeed.
|
|
(This is why image-pdf has file ext pdf but type EPS; this tricks xmlto in
|
|
doing the right thing)
|
|
xmlto pdf gstreamer-whatever.xml generates pdf (but seems to fail on the
|
|
FAQ, so for now we use ps2pdf)
|
|
|
|
HOW THE BUILD SYSTEM IS SET UP
|
|
------------------------------
|
|
* make all should build html, ps, and pdf
|
|
* html is built in a subdir, with the png/ps images copied there
|
|
* ps and pdf are built in the current dir, in one file
|
|
|
|
|
|
DOCBOOK NOTES
|
|
=============
|
|
|
|
* spell checking with aspell
|
|
* aspell -b -c --mode=sgml --lang=en <file>.xml
|
|
unfortunately the curses-ui of aspell (0.50.5) has problems with the xml tags
|
|
|
|
|
|
GTK-DOC NOTES
|
|
=============
|
|
|
|
* files under CVS control:
|
|
- Makefile.am
|
|
- gstreamer-sections.txt
|
|
describes which symbols later appear on one api-doc page
|
|
configure which symbols are shown/invisible/private
|
|
- gstreamer.types
|
|
the types file lists all get_type() functions that register the GObject types
|
|
- gstreamer-docs.sgml
|
|
defines the overall structure of the api documentation
|
|
- tmpl/
|
|
- only add the file to CVS if you have at least filled the short description
|
|
(filename corresponds to the <FILE> tag in the sections file)
|
|
- document as much as possible in the source (*.c files)
|
|
|
|
* what to do when adding a new piece of API:
|
|
- add both an entity and use the entity in gstreamer-docs.sgml
|
|
- add a new <SECTION> to gstreamer-sections.txt in the correct alphabetical
|
|
position related to the other sections (so that it is easier to locate)
|
|
- add all documented symbols to gstreamer-sections.txt in the proper section
|
|
(default),<SUBSECTION Standard>,<SUBSECTION Private>
|
|
- document at least the Short_Description in tmpl/.sgml
|
|
- document symbols where they are definied, so that when one changes the
|
|
definition, the chaces are good that docs are updated.
|
|
- document functions, signals in the .c files
|
|
- document structs, typedefs, enums in the .h files
|
|
|
|
* checklist:
|
|
- make sure *-sections.txt has a <TITLE> set for each <FILE>
|
|
- add only *one* <TITLE> to each file, when you have multiple classes in one
|
|
source-file, create one <FILE> section for each class
|
|
- the <TITLE> *must* be named like the type of the GType, when it gets
|
|
registered (otherwise gtkdoc introspection fails)
|
|
- for clarity name the <FILE> like the <TITLE>, but all lowercase
|
|
|
|
* 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
|
|
- gtk docs does not warns about empty member docs!, run
|
|
find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@.*: *$" {} \;
|
|
in the project root to find them
|
|
- gtk docs 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 gtk-doc build ?
|
|
- Scan step:
|
|
- based on a $(MODULE).types file:
|
|
- gtkdoc-scangobj creates a gtkdoc-scan binary
|
|
- using CC, LD, CFLAGS, LDFLAGS env var
|
|
- using --type-init-func and --module parameters
|
|
- gtkdoc-scan creates
|
|
- $MODULE.signals.new
|
|
- $MODULE.hierarchy.new
|
|
- $MODULE.interfaces.new
|
|
- $MODULE.prerequisites.new
|
|
- $MODULE.args.new
|
|
- generated source and objects get deleted
|
|
- gtkdoc-scangobj merges changes into the original files
|
|
- gtkdoc-scan
|
|
- extracts decls of functions, macros, enums, structs, unions from headers
|
|
- generates
|
|
- $MODULE-decl.txt
|
|
- $MODULE-decl-list.txt
|
|
- $MODULE-decl-list.txt then should get copied to $MODULE-sections.txt
|
|
- scan-build.stamp gets created
|
|
|
|
- Template generation step:
|
|
- gtkdoc-mktmpl --module=$MODULE
|
|
- reads in tmpl/*.sgml
|
|
- moves them to tmpl/*.sgml.bak
|
|
- recreates tmpl/*.sgml according to $MODULE-sections.txt
|
|
- moves unused stuff to $MODULE-unused.txt
|
|
- tmpl-build.stamp gets generated
|
|
|
|
* Possible errors and how to fix them
|
|
- Warning: multiple "IDs" for constraint linkend: gst-tag-register.
|
|
- check if gst_tag_register is listed more than once in -sections.txt
|
|
|
|
STYLE GUIDE FOR GTK-DOC
|
|
=======================
|
|
- this is in addition to gtk-doc's style-guide.txt
|
|
|
|
- when documenting signals, use "the #Gst..." for the object receiving the
|
|
signal; no trailing dot, and no "that received the signal"
|
|
- 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
|
|
|
|
- the bottom of the description should say when the doc was last reviewed
|
|
(version and date)
|
|
* Last reviewed on 2005-10-28 (0.9.4)
|
|
|
|
WEBSITE DOCUMENTATION
|
|
=====================
|
|
|
|
Updating the online documentation is pretty simple.
|
|
Make sure that you
|
|
a) have a working freedesktop.org account
|
|
b) $HOME/.ssh/config set up so that it has the right User for the Host
|
|
(for example, I have:
|
|
Host freedesktop.org
|
|
User thomasvs
|
|
c) verify this works by doing ssh freedesktop.org and being logged in without
|
|
a password prompt
|
|
d) have verified your changes build documentation locally.
|
|
|
|
Then, after updating any of the docs, run "make upload" from that directory.
|
|
Or, run "make upload" from this (docs) directory.
|
|
|
|
DOCUMENTING ELEMENTS
|
|
====================
|
|
As of september 2005 we have some system to document plugins and elements
|
|
in the various plugin packages.
|
|
|
|
- in a submodule, docs go in docs/plugins
|
|
- template can be copied from gst-plugins-base
|
|
- to add an element to be documented:
|
|
- add an include href in the Elements chapter for the element
|
|
in the main .sgml
|
|
- add a section for it in -sections.txt with
|
|
<FILE>element-(element)</FILE>
|
|
<TITLE>(element)</TITLE>
|
|
- add a gtk-doc section to the source code like:
|
|
/**
|
|
* SECTION:element-multifdsink
|
|
|
|
and fill it with documentation about the element, preferably inside
|
|
a <refsect2> docbook container.
|
|
- add an example:
|
|
- either a few pipelines, inside <programlisting>
|
|
- or a piece of code:
|
|
- create an example program (element)-example.c in the plugin dir
|
|
- add the full path (starting with $(top_srcdir)) for this example
|
|
to the EXAMPLE_CFILES variable in Makefile.am
|
|
- add an xinclude of a file named "element-(element)-example.xml"
|
|
to the docbook documentation piece in the element source code
|
|
- add the header to EXTRA_HFILES in Makefile.am to be able to document
|
|
signals and args; in that case, the object struct needs to be in
|
|
-sections.txt outside of the Standard Subsection (which is annoying,
|
|
but ...)
|
|
(FIXME: are we sure we can both do the xinclude from the tmpl/ sgml,
|
|
as well as an override from the source itself ? maybe we should just
|
|
make sure the xinclude is in the source itself instead ?)
|
|
- to rebuild the docs, do:
|
|
make clean
|
|
make inspect-update
|
|
make
|
|
- examples will only show up using gtk-doc 1.4 or later - it relies on
|
|
merging stuff from .sgml with inline docs. We might want to change
|
|
this to only get stuff from the source.
|
|
|
|
- to add a plugin to be documented:
|
|
- make sure inspect/ has generated a .xml file for it
|
|
- add it to CVS
|
|
- add an include in -docs.sgml in the Plugins list for that plugin
|
|
|
|
- possible errors:
|
|
"multiple constraints for linkend ID": check if each section in
|
|
-sections.txt actually starts and ends with <SECTION> and </SECTION>
|
|
|
|
RANDOM THINGS I'VE LEARNED
|
|
==========================
|
|
|
|
* for clean builddir != srcdir separation, I wanted to use xmlto --searchpath
|
|
so the source xml could find the built entity file.
|
|
But xmlto --searchpath is (right now) for TeX input, not xml input.
|
|
xsltproc has a --path option (that xmlto doesn't use yet), but it
|
|
resolves single files to $(specified_path)/$(srcdir)/$(file)
|
|
For now, we need to hack around it by copying xml to the build dir.
|
|
|
|
|