docs/README: Some more details about how the plugin docs works.

Original commit message from CVS:
* docs/README:
Some more details about how the plugin docs works.
* docs/plugins/gstreamer-plugins-sections.txt:
Whitespace cleanup.
This commit is contained in:
Stefan Kost 2008-02-01 12:25:17 +00:00
parent a9b5a4d56c
commit 036d5105f5
3 changed files with 48 additions and 14 deletions

View file

@ -1,3 +1,11 @@
2008-02-01 Stefan Kost <ensonic@users.sf.net>
* docs/README:
Some more details about how the plugin docs works.
* docs/plugins/gstreamer-plugins-sections.txt:
Whitespace cleanup.
2008-02-01 Stefan Kost <ensonic@users.sf.net> 2008-02-01 Stefan Kost <ensonic@users.sf.net>
* gst/parse/grammar.tab.pre.c: * gst/parse/grammar.tab.pre.c:

View file

@ -243,12 +243,29 @@ in the various plugin packages.
cvs add inspect cvs add inspect
cvs add inspect/*.xml cvs add inspect/*.xml
- 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: - 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 .sgml in the main -docs.sgml
- add a section for it in -sections.txt with - add a section for it in -sections.txt with
<SECTION>
<FILE>element-(element)</FILE> <FILE>element-(element)</FILE>
<TITLE>(element)</TITLE> <TITLE>(element)</TITLE>
GstXxx
<SUBSECTION Standard>
GstXxxClass
GST_XXX
GST_XXX_CLASS
GST_IS_XXX
GST_IS_XXX_CLASS
GST_TYPE_XXX
gst_xxx_get_type
</SECTION>
- add a gtk-doc section to the source code like: - add a gtk-doc section to the source code like:
/** /**
* SECTION:element-multifdsink * SECTION:element-multifdsink
@ -272,8 +289,7 @@ in the various plugin packages.
make sure the xinclude is in the source itself instead ?) make sure the xinclude is in the source itself instead ?)
- to rebuild the docs, do: - to rebuild the docs, do:
make clean make clean
make scanobj-update make update
make inspect-update
make make
- examples will only show up using gtk-doc 1.4 or later - it relies on - 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 merging stuff from .sgml with inline docs. We might want to change
@ -282,15 +298,27 @@ in the various plugin packages.
- changes to *.signals and *.args - changes to *.signals and *.args
- new files for your plugin created in inspect/ - new files for your plugin created in inspect/
- to add a plugin to be documented: - the plugin-doc-list on the gstreamer homepage is updated along with other
- make sure inspect/ has generated a .xml file for it. If it has not, make web site updates.
sure you have pygst installed and run 'make update-inspect'.
- add it to CVS - maintainer tricks:
- add an include in -docs.sgml in the Plugins list for that plugin - 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/\(.*\)/ \<xi:include href=\"\1\" \/\>/"
ls -1 xml/element-*.xml | grep -v -- "-details.xml" | sort | sed -e "s/\(.*\)/ \<xi:include href=\"\1\" \/\>/"
- 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: - possible errors:
"multiple constraints for linkend ID": check if each section in - "multiple constraints for linkend ID":
-sections.txt actually starts and ends with <SECTION> and </SECTION> check if each section in -sections.txt actually starts and ends with
<SECTION> and </SECTION>
- if a plugin does not show up:
- check inspect/plugin-xxx.xml and inspect/elements-
RANDOM THINGS I'VE LEARNED RANDOM THINGS I'VE LEARNED
========================== ==========================
@ -344,7 +372,7 @@ Check http://www.imendio.com/projects/devhelp/
It's a really nice development app allowing you to look up API stuff 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 ;) from various gtk-doc'd libraries. GStreamer is one of these ;)
gtk-doc generates both html API docs and the matching .devhelp files gtk-doc generates both html API docs and the matching .devhelp(2) books.
IMAGES IMAGES
------ ------

View file

@ -17,7 +17,6 @@ GST_IS_FAKE_SRC_CLASS
gst_fake_src_get_type gst_fake_src_get_type
</SECTION> </SECTION>
<SECTION> <SECTION>
<FILE>element-fakesink</FILE> <FILE>element-fakesink</FILE>
<TITLE>fakesink</TITLE> <TITLE>fakesink</TITLE>
@ -80,7 +79,6 @@ GST_IS_FILE_SRC_CLASS
gst_file_src_get_type gst_file_src_get_type
</SECTION> </SECTION>
<SECTION> <SECTION>
<FILE>element-filesink</FILE> <FILE>element-filesink</FILE>
<TITLE>filesink</TITLE> <TITLE>filesink</TITLE>