summaryrefslogtreecommitdiffstats
path: root/doc/common/README.Doxygen
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commitce4a32fe52ef09d8f5ff1dd22c001110902b60a2 (patch)
tree5ac38a06f3dde268dc7927dc155896926aaf7012 /doc/common/README.Doxygen
downloadtdelibs-ce4a32fe52ef09d8f5ff1dd22c001110902b60a2.tar.gz
tdelibs-ce4a32fe52ef09d8f5ff1dd22c001110902b60a2.zip
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'doc/common/README.Doxygen')
-rw-r--r--doc/common/README.Doxygen116
1 files changed, 116 insertions, 0 deletions
diff --git a/doc/common/README.Doxygen b/doc/common/README.Doxygen
new file mode 100644
index 000000000..77b6bfe5f
--- /dev/null
+++ b/doc/common/README.Doxygen
@@ -0,0 +1,116 @@
+***
+*** README for KDE's Doxygen tools
+***
+
+This directory contains tools and data files for Doxygen
+generation. These are the GENERIC files; any module may
+override them by putting specific replacements in doc/api/ .
+This allows modules to customize their appearance as desired.
+The files that may be overridden are:
+
+- doxygen.css Stylesheet.
+- mainheader.html Header for front page of dox. This should
+ not be terribly different from header.html.
+ It might contain special CSS for the footer.
+- mainfooter.html Footer for front page of dox. This should at
+ least credit Doxygen [1] and point to the dox
+ guidelines [2].
+- header.html Header file for regular pages.
+- footer.html Footer file for regular pages.
+- Doxyfile.global The global (brief) Doxyfile. For a long-style
+ Doxyfile, see KDE PIM's doc/api/Doxyfile.pim.
+
+The tool for generating dox lives in admin/ :
+
+- doxygen.sh Script that does all the dox generation work.
+ See below for usage information.
+
+
+In a configured build directory, you can use "make apidox" to
+generate the API dox for the module -- assuming it has any, of course.
+Writing dox is beyond the scope of this README -- see the notes at
+http://techbase.kde.org/Policies/Library_Documentation_Policy .
+You can generate dox by hand -- without even having a configured
+build directory -- as explained below. There is also documentation
+for the special tags you can enter in Makefile.am anywhere
+in a module to modify dox generation.
+
+
+
+***
+*** Tool usage.
+***
+
+Usage:
+
+doxygen.sh [--recurse] [--modulename] [--doxdatadir=<dir>] [--installdir=<dir>]
+ <top_srcdir> [<subdir>]
+
+--recurse Also generate dox in subdirs of the given <subdir>. If no
+ <subdir> is given, --recurse is the default and can be
+ turned off with --no-recurse.
+--modulename By default, apidox are generated in a subdirectory
+ <modulename>-apidocs/ . You can use --no-modulename to
+ suppress the <modulename> and generate the apidox in
+ a subdirectory apidocs/ . Modulename is the last part of
+ the <top_srcdir> (usually a KDE SVN module name).
+--doxdatadir=<dir> Locate the HTML header files and support graphics.
+ In kdelibs, the subdirectory doc/common/ contains these
+ files (and this README). In an installed KDE system,
+ $KDEDIR/share/doc/HTML/en/common/ contains a copy.
+ This argument is mandatory if doxygen.sh can't guess where
+ the doxdata lives.
+--installdir=<dir> Locate the directory where apidox from other modules
+ is installed. Subdirectories named *-apidocs/ under the
+ named <dir> are searched for tag files, for cross-module
+ cross-referencing.
+
+
+
+How to generate dox manually: <TODO>
+Plan to fit these tools into ../Doxyfile.am: <TODO>
+Differences with current dox: <TODO>
+
+# A shell script that builds dox without all the tedious mucking about with
+# autoconf and configure. Run it in the "top builddir" with one argument,
+# the "top srcdir". Something like this:
+#
+# cd /mnt/build/kdepim
+# sh /mnt/src/kdepim/doc/api/doxygen.sh /mnt/src/kdepim
+#
+# You can also build single subdirs (for instance, after updating some
+# dox and you don't want to rebuild for the enitre module) by giving the
+# subdirectory _relative to the top srcdir_ as a second argument:
+#
+# sh /mnt/src/kdepim/doc/api/doxygen.sh /mnt/src/kdepim kpilot/lib
+#
+# When generating dox for kdelibs, a tag file for Qt is also created.
+# The location of Qt is specified indirectly through $QTDOCDIR or,
+# if that is not set, $QTDIR, or otherwise guessed. You may explicitly
+# set the location of a pre-generated tag file with $QTDOCTAG. One
+# typical approach might be:
+#
+# QTDOCTAG=$QTDIR/doc/qt.tag QTDOCDIR=http://doc.trolltech.com/3.3/
+#
+# Finally, there is a --no-recurse option for top-level generation
+# that avoids generating all the subdirectories as well. It also
+# suppresses cleaning up (rm -rf) of the dox direction beforehand.
+#
+# Post-finally, there is a --no-modulename option that builds the
+# dox in "apidocs/" instead of "modulename-apidocs". The former is
+# compatible with the KDE 3.4 build system, the latter is more convenient
+# for the installed dox.
+
+#
+# A shell script to post-process doxy-generated files; the purpose
+# is to make the menu on the left in the file match the actually
+# generated files (ie. leave out namespaces if there are none).
+#
+# Usage: doxyndex.sh <toplevel-apidocs-dir> <relative-html-output-directory>
+#
+# Typically, this means $(top_builddir)/apidocs and something like
+# libfoo/html for the output. For the top-level dig, set relative-html
+# to "." . In non-top directories, both <!-- menu --> and <!-- gmenu -->
+# are calculated and replaced. Top directories get an empty <!-- menu -->
+# if any.
+