X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=docs%2FREADME;h=a7b46fe05e8987aa4bd8d59156d4bd42825c544f;hb=5470f6df00595f4ab44871e0e633bf15006abc5c;hp=1f9670cfa515b74757a47ecdc522d312a065fe7f;hpb=58a4a1a7bf21f104e5b6a0ad065fc9b850b398a4;p=platform%2Fupstream%2Fgstreamer.git diff --git a/docs/README b/docs/README index 1f9670c..a7b46fe 100644 --- a/docs/README +++ b/docs/README @@ -6,12 +6,16 @@ IMPORTANT Please make sure you've read and understood everything in this file before you try changing documentation. +Some of the docbook-related bits in this README might be out of date now that +quite a bit of the documentation has moved into the gst-docs repository. + 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) +* FAQ / Application Development Manual / Plugin Writer's Guide / Tutorials - + these are maintained in markdown format and live in the gst-docs repository. DOCBOOK NOTES ============= @@ -26,7 +30,7 @@ OVERVIEW * The source for the documentation is: - one or more .xml files, with the main one being gstreamer-(whatever).xml - image files - - in .fig + - in .svg - in .png (and maybe others) * We want to generate docs in HTML, PS and PDF * We want to use xml to to generate these @@ -86,11 +90,9 @@ HOW THE BUILD SYSTEM IS SET UP * 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 +SPELL CHECKING +-------------- +* with aspell * aspell -b -c --mode=sgml --lang=en .xml unfortunately the curses-ui of aspell (0.50.5) has problems with the xml tags @@ -98,7 +100,7 @@ DOCBOOK NOTES GTK-DOC NOTES ============= -* files under CVS control: +* files under revision control: - Makefile.am - gstreamer-sections.txt describes which symbols later appear on one api-doc page @@ -119,7 +121,7 @@ GTK-DOC NOTES - add all documented symbols to gstreamer-sections.txt in the proper section (default),, - document at least the Short_Description in tmpl/.sgml - - document symbols where they are definied, so that when one changes the + - document symbols where they are defined, 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 @@ -178,6 +180,30 @@ GTK-DOC NOTES - 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 +- link to signals from the description like this: + * The element-added signal + WEBSITE DOCUMENTATION ===================== @@ -202,11 +228,50 @@ in the various plugin packages. - in a submodule, docs go in docs/plugins - template can be copied from gst-plugins-base +- to add plugins documentation: + - create docs/plugins + - create Makefile.am and friends, add to configure.ac + - create docs/version.entities.in, add to configure.ac + - in docs/plugins: + - create $(module)-plugins.types with #include + - run make + - edit the -docs.sgml + - add to cvs: + 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 + cvs add inspect + cvs add inspect/*.xml + - Additional types can be added to the documentation by placing them in + the .types file like this: + type:GstPlayBaseBin + This is useful for documenting plugin-private types that implement + signals or properties. The GType is looked up by name after all the + element classes have been printed - so this is only useful for types + that are created as a consequence of loading plugins and registering + the element(s). + +- to add a plugin to be documented: + - make sure inspect/ has generated a inspect/plugin-xxx.xml file for it. + - if it has not, make sure you have pygst installed and run 'make update'. + and add it to CVS. + - add an xi:include in -docs.sgml in the Plugins chapter for that plugin + - to add an element to be documented: - - add an include href in the Elements chapter for the element + - add an xi:include in the Elements chapter for the element + in the main -docs.sgml - add a section for it in -sections.txt with +
element-(element) (element) + GstXxx + + GstXxxClass + GST_XXX + GST_XXX_CLASS + GST_IS_XXX + GST_IS_XXX_CLASS + GST_TYPE_XXX + gst_xxx_get_type +
- add a gtk-doc section to the source code like: /** * SECTION:element-multifdsink @@ -222,19 +287,60 @@ in the various plugin packages. - 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 + 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 ?) + - if the plugin has no public header, don't add the c-file, add entries to the + -overrides.txt file (see playbin docs in plugins-base). - to rebuild the docs, do: make clean - make inspect-update + make update make - -- 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 + - 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. + - you need to commit resulting files to git: + - changes to *.signals and *.args + - new files for your plugin created in inspect/ + - if you get this warning: + " Documentation in template xxx for ./tmpl/element-yyy:Short_Description + being overridden by inline comments" + per-default the description from the GST_ELEMENT_DETAILS is put to the + Short_Description. This warning mean you have a different one in the section + docs as "@short_description:". + +- the plugin-doc-list on the gstreamer homepage is updated along with other + web site updates. + +- maintainer tricks: + - in gst-plugins-foo/docs/plugins/, run + make check-inspected-versions + to show plugins whose inspect information is not up-to-date (which is + usually either because they have been moved to a different module or + because they are not built on the maintainer's machine for some reason). + Whether it really makes sense to update the version number is debatable + (after all, the inspected information may be outdated and things may have + changed, in which case it would be bad to change the version number) + - find files that have docs + 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 + 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 + - add those .h files to EXTRA_HFILES in Makefile.am + - update gst-plugins-xxx-docs.sgml + cd docs/plugins + ls -1 xml/plugin-*.xml | sort | sed -e "s/\(.*\)/ \/" + ls -1 xml/element-*.xml | grep -v -- "-details.xml" | sort | sed -e "s/\(.*\)/ \/" + - maybe we can generate these lists after "make update" and just xi:include + them in gst-plugins-xxx-docs.sgml. They should be committed to the vcs. + +- possible errors: + - "multiple constraints for linkend ID": + check if each section in -sections.txt actually starts and ends with +
and
+ - if a plugin does not show up: + - check inspect/plugin-xxx.xml and tmpl/elements- RANDOM THINGS I'VE LEARNED ========================== @@ -247,3 +353,16 @@ RANDOM THINGS I'VE LEARNED For now, we need to hack around it by copying xml to the build dir. +DEVHELP INTEGRATION +------------------- +Check https://wiki.gnome.org/Apps/Devhelp +It's a really nice development app allowing you to look up API stuff +from various gtk-doc'd libraries. GStreamer is one of these ;) + +gtk-doc generates both html API docs and the matching .devhelp(2) books. + +IMAGES +------ +It's important to keep the original source format for images, to be able +to change and regenerate later on. Original files go in +docs/images