1 GStreamer documentation notes
6 Please make sure you've read and understood everything in this file
7 before you try changing documentation.
9 Some of the docbook-related bits in this README might be out of date now that
10 quite a bit of the documentation has moved into the gst-docs repository.
15 GStreamer has two sets of documentation that we maintain:
16 * API references, using gtk-doc (gstreamer, gstreamer-libs)
17 * FAQ / Application Development Manual / Plugin Writer's Guide / Tutorials -
18 these are maintained in markdown format and live in the gst-docs repository.
23 OK, I've grown so tired of having to coax the docs to build every time I
24 get round to it that I've decided to note down some of the things that
25 are important to know.
29 * Our documentation should all be Docbook/XML. No SGML.
30 * The source for the documentation is:
31 - one or more .xml files, with the main one being gstreamer-(whatever).xml
34 - in .png (and maybe others)
35 * We want to generate docs in HTML, PS and PDF
36 * We want to use xml to to generate these
40 We stick to some simple conventions for writing docbook documentation.
42 - all id's start with chapter-, part-, section-, or misc-
43 - verify this is the case by looking at the generated file names in html/
44 - sections should also include the chapter name;
45 for example in a chapter called chapter-example, a section would be
46 called section-example-hello-world
47 * there are currently comments of the form <!-- synchronize with PWG -->
48 in the docbook file. Please check the relevant section of the other manual
51 HOW IMAGES ARE HANDLED
52 ----------------------
53 * the format of images used is:
58 * images may need to be converted from their source format to the end format
60 * a file called image.entities is generated that provides two entities:
62 ℑ is the file extension (png, ps, pdf)
63 * all generated images will be put in images/
65 HOW THE BUILD WORKS FOR EACH FORMAT
66 -----------------------------------
68 - xmlto html gstreamer-whatever.xml should produce the html docs.
69 - We do this in the html subdir of the doc builddir.
70 - images are copied to (builddir)/html/images
71 - PNGS should be set to all of the png's referenced for html, both
72 already there and auto-generated
75 - images are converted to .ps files in EPS format. Generated images are
77 - xmlto ps gstreamer-whatever.xml generates the ps file
81 - ps2pdf is the easiest
82 - we specify ps, PS as the image type, but using xmlto the build will fail
83 because it uses ps2pdf internally and it fails to generate the images
84 By hand-generating .pdf images before xmlto we can make the build succeed.
85 (This is why image-pdf has file ext pdf but type EPS; this tricks xmlto in
86 doing the right thing)
87 xmlto pdf gstreamer-whatever.xml generates pdf (but seems to fail on the
88 FAQ, so for now we use ps2pdf)
90 HOW THE BUILD SYSTEM IS SET UP
91 ------------------------------
92 * make all should build html, ps, and pdf
93 * html is built in a subdir, with the png/ps images copied there
94 * ps and pdf are built in the current dir, in one file
99 * aspell -b -c --mode=sgml --lang=en <file>.xml
100 unfortunately the curses-ui of aspell (0.50.5) has problems with the xml tags
106 * files under revision control:
108 - gstreamer-sections.txt
109 describes which symbols later appear on one api-doc page
110 configure which symbols are shown/invisible/private
112 the types file lists all get_type() functions that register the GObject types
113 - gstreamer-docs.sgml
114 defines the overall structure of the api documentation
116 - only add the file to CVS if you have at least filled the short description
117 (filename corresponds to the <FILE> tag in the sections file)
118 - document as much as possible in the source (*.c files)
120 * what to do when adding a new piece of API:
121 - add both an entity and use the entity in gstreamer-docs.sgml
122 - add a new <SECTION> to gstreamer-sections.txt in the correct alphabetical
123 position related to the other sections (so that it is easier to locate)
124 - add all documented symbols to gstreamer-sections.txt in the proper section
125 (default),<SUBSECTION Standard>,<SUBSECTION Private>
126 - document at least the Short_Description in tmpl/.sgml
127 - document symbols where they are defined, so that when one changes the
128 definition, the chaces are good that docs are updated.
129 - document functions, signals in the .c files
130 - document structs, typedefs, enums in the .h files
133 - make sure *-sections.txt has a <TITLE> set for each <FILE>
134 - add only *one* <TITLE> to each file, when you have multiple classes in one
135 source-file, create one <FILE> section for each class
136 - the <TITLE> *must* be named like the type of the GType, when it gets
137 registered (otherwise gtkdoc introspection fails)
138 - for clarity name the <FILE> like the <TITLE>, but all lowercase
140 * what to do when trying to improve the docs
141 - compare the output of
142 grep "_get_type" gstreamer-sections.txt | sort
143 with the types in XXX.types to detect entries that
145 - gtk docs does not warns about empty member docs!, run
146 find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@.*: *$" {} \;
147 in the project root to find them
148 - gtk docs does not warns about empty Returns: docs!, run
149 find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@Returns: *$" {} \;
150 in the project root to find them
152 * what happens during a gtk-doc build ?
154 - based on a $(MODULE).types file:
155 - gtkdoc-scangobj creates a gtkdoc-scan binary
156 - using CC, LD, CFLAGS, LDFLAGS env var
157 - using --type-init-func and --module parameters
158 - gtkdoc-scan creates
159 - $MODULE.signals.new
160 - $MODULE.hierarchy.new
161 - $MODULE.interfaces.new
162 - $MODULE.prerequisites.new
164 - generated source and objects get deleted
165 - gtkdoc-scangobj merges changes into the original files
167 - extracts decls of functions, macros, enums, structs, unions from headers
170 - $MODULE-decl-list.txt
171 - $MODULE-decl-list.txt then should get copied to $MODULE-sections.txt
172 - scan-build.stamp gets created
174 - Template generation step:
175 - gtkdoc-mktmpl --module=$MODULE
176 - reads in tmpl/*.sgml
177 - moves them to tmpl/*.sgml.bak
178 - recreates tmpl/*.sgml according to $MODULE-sections.txt
179 - moves unused stuff to $MODULE-unused.txt
180 - tmpl-build.stamp gets generated
182 * Possible errors and how to fix them
183 - Warning: multiple "IDs" for constraint linkend: gst-tag-register.
184 - check if gst_tag_register is listed more than once in -sections.txt
186 STYLE GUIDE FOR GTK-DOC
187 =======================
188 - this is in addition to gtk-doc's style-guide.txt
190 - when documenting signals, use "the #Gst..." for the object receiving the
191 signal; no trailing dot, and no "that received the signal"
192 - function/macro descriptions are descriptive, not imperative
193 ie, it uses the third person verb
194 - synopsis and description should have most-used/application functions at the
196 - functions that can return FALSE/NULL or fail should describe their failure
197 conditions like this:
198 * Returns NULL if no element with the given name is found in the bin, if
199 * the frobble was stuck in the froob, or the frizzle was frazzed.
200 - a line with function attributes should be added before Returns:
202 "MT safe." - the function is verified to be multithreadingsafe
203 "Caller owns returned reference" for refcounted classes
204 "Caller owns returned value" for other types (iterators, ..)
205 - we do this because, in contrast with GLib/GTK, we are more explicit
206 about threadsafety and related issues
207 - link to signals from the description like this:
208 * The <link linkend="GstBin-element-added">element-added</link> signal
210 WEBSITE DOCUMENTATION
211 =====================
213 Updating the online documentation is pretty simple.
215 a) have a working freedesktop.org account
216 b) $HOME/.ssh/config set up so that it has the right User for the Host
217 (for example, I have:
220 c) verify this works by doing ssh freedesktop.org and being logged in without
222 d) have verified your changes build documentation locally.
224 Then, after updating any of the docs, run "make upload" from that directory.
225 Or, run "make upload" from this (docs) directory.
229 As of september 2005 we have some system to document plugins and elements
230 in the various plugin packages.
232 - in a submodule, docs go in docs/plugins
233 - template can be copied from gst-plugins-base
234 - to add plugins documentation:
235 - create docs/plugins
236 - create Makefile.am and friends, add to configure.ac
237 - create docs/version.entities.in, add to configure.ac
239 - create $(module)-plugins.types with #include <gst/gst.h>
241 - edit the -docs.sgml
243 cvs add *-plugins-docs.sgml *-plugins.args *-plugins.hierarchy *-plugins.interfaces *-plugins.prerequisites *-plugins.signals *-plugins.types inspect-build.stamp inspect.stamp scanobj-build.stamp
245 cvs add inspect/*.xml
246 - Additional types can be added to the documentation by placing them in
247 the .types file like this:
249 This is useful for documenting plugin-private types that implement
250 signals or properties. The GType is looked up by name after all the
251 element classes have been printed - so this is only useful for types
252 that are created as a consequence of loading plugins and registering
255 - to add a plugin to be documented:
256 - make sure inspect/ has generated a inspect/plugin-xxx.xml file for it.
257 - if it has not, make sure you have pygst installed and run 'make update'.
259 - add an xi:include in -docs.sgml in the Plugins chapter for that plugin
261 - to add an element to be documented:
262 - add an xi:include in the Elements chapter for the element
263 in the main -docs.sgml
264 - add a section for it in -sections.txt with
266 <FILE>element-(element)</FILE>
267 <TITLE>(element)</TITLE>
269 <SUBSECTION Standard>
278 - add a gtk-doc section to the source code like:
280 * SECTION:element-multifdsink
282 and fill it with documentation about the element, preferably inside
283 a <refsect2> docbook container.
285 - either a few pipelines, inside <programlisting>
286 - or a piece of code:
287 - create an example program (element)-example.c in the plugin dir
288 - add the full path (starting with $(top_srcdir)) for this example
289 to the EXAMPLE_CFILES variable in Makefile.am
290 - add an xinclude of a file named "element-(element)-example.xml"
291 to the docbook documentation piece in the element source code
292 - add the header to EXTRA_HFILES in Makefile.am to be able to document
293 signals and args; in that case, the object struct needs to be in
294 -sections.txt outside of the Standard Subsection (which is annoying,
296 (FIXME: are we sure we can both do the xinclude from the tmpl/ sgml,
297 as well as an override from the source itself ? maybe we should just
298 make sure the xinclude is in the source itself instead ?)
299 - if the plugin has no public header, don't add the c-file, add entries to the
300 -overrides.txt file (see playbin docs in plugins-base).
301 - to rebuild the docs, do:
305 - examples will only show up using gtk-doc 1.4 or later - it relies on
306 merging stuff from .sgml with inline docs. We might want to change
307 this to only get stuff from the source.
308 - you need to commit resulting files to git:
309 - changes to *.signals and *.args
310 - new files for your plugin created in inspect/
311 - if you get this warning:
312 " Documentation in template xxx for ./tmpl/element-yyy:Short_Description
313 being overridden by inline comments"
314 per-default the description from the GST_ELEMENT_DETAILS is put to the
315 Short_Description. This warning mean you have a different one in the section
316 docs as "@short_description:".
318 - the plugin-doc-list on the gstreamer homepage is updated along with other
322 - in gst-plugins-foo/docs/plugins/, run
323 make check-inspected-versions
324 to show plugins whose inspect information is not up-to-date (which is
325 usually either because they have been moved to a different module or
326 because they are not built on the maintainer's machine for some reason).
327 Whether it really makes sense to update the version number is debatable
328 (after all, the inspected information may be outdated and things may have
329 changed, in which case it would be bad to change the version number)
330 - find files that have docs
331 for file in `find . -name "*.c" -exec grep -l " * SECTION:element-" {} \; | sort`; do if [ -e ${file/.c/.h} ]; then echo ${file/.c/.h}; else echo "no header for $file"; fi; done
332 for file in `find . -name "*.cc" -exec grep -l " * SECTION:element-" {} \; | sort`; do if [ -e ${file/.cc/.h} ]; then echo ${file/.cc/.h}; else echo "no header for $file"; fi; done
333 - add those .h files to EXTRA_HFILES in Makefile.am
334 - update gst-plugins-xxx-docs.sgml
336 ls -1 xml/plugin-*.xml | sort | sed -e "s/\(.*\)/ \<xi:include href=\"\1\" \/\>/"
337 ls -1 xml/element-*.xml | grep -v -- "-details.xml" | sort | sed -e "s/\(.*\)/ \<xi:include href=\"\1\" \/\>/"
338 - maybe we can generate these lists after "make update" and just xi:include
339 them in gst-plugins-xxx-docs.sgml. They should be committed to the vcs.
342 - "multiple constraints for linkend ID":
343 check if each section in -sections.txt actually starts and ends with
344 <SECTION> and </SECTION>
345 - if a plugin does not show up:
346 - check inspect/plugin-xxx.xml and tmpl/elements-
348 RANDOM THINGS I'VE LEARNED
349 ==========================
351 * for clean builddir != srcdir separation, I wanted to use xmlto --searchpath
352 so the source xml could find the built entity file.
353 But xmlto --searchpath is (right now) for TeX input, not xml input.
354 xsltproc has a --path option (that xmlto doesn't use yet), but it
355 resolves single files to $(specified_path)/$(srcdir)/$(file)
356 For now, we need to hack around it by copying xml to the build dir.
359 (old) DOCUMENTATION BUILDING NOTES
360 ----------------------------------
362 To build the GStreamer documentation you need the following installed (based on
363 Red Hat packages). These packages comes from rawhide and are the ones that
364 will be in Red Hat 7.3/8.0
369 openjade (needs to be rebuilt from SRPM for Red Hat 7.2)
395 Check http://www.imendio.com/projects/devhelp/
396 It's a really nice development app allowing you to look up API stuff
397 from various gtk-doc'd libraries. GStreamer is one of these ;)
399 gtk-doc generates both html API docs and the matching .devhelp(2) books.
403 It's important to keep the original source format for images, to be able
404 to change and regenerate later on. Original files go in