Development/Tools/apidox: Difference between revisions

Latest revision as of 05:40, 2 June 2019

Warning

This page needs a review and probably holds information that needs to be fixed.

Parts to be reviewed:

Update to kapidox and KF5
Update link to community

The KDE project uses doxygen to generate API documentation from source code.

Please see our documentation policy and tutorial.

Generating

HTML pages

Generate apidox in the KDE format using

% cd html_dir
% /path/to/trunk/KDE/kdelibs/doc/api/doxygen.sh --recurse \
    --doxdatadir=/path/to/trunk/KDE/kdelibs/doc/common \
    /path/to/trunk/KDE/kdelibs

Notes:

You must type the paths in full - the script doesn't understand tilde ('~') representing your home directory. However, you can use the $HOME environment variable instead.

The QTDOCDIR environment variable should point to the html folder of the Qt documentation. If QTDOCDIR is not set, doxygen.sh will try to find the documentation based on the value of QTDIR.

To generate documentation in doxygen style instead of KDE style, use kdedoxygen.sh:

% cd source_dir
% /path/to/trunk/KDE/kdesdk/scripts/kdedoxygen.sh

You'll find the top-level html at ./apidocs/html/index.html Load that page into your favorite web browser, review your documentation, then edit your code accordingly.

Warnings from doxygen will be found in ./doxygen.log. Please try to fix all warnings reported by doxygen.

Man pages

Man page lovers can generate man pages using kdedoxyman.sh Like so:

% cd source_dir
% /path/trunk/KDE/kdesdk/scripts/kdedoxyman.sh -d /path/kdeinstall/share

You can also generate man pages from Qt source code using kdedoxyman.sh:

% cd qt-copy/src
% /path/trunk/KDE/kdesdk/scripts/kdedoxyman.sh -d /path/kdeinstall/share

and then add /path/kdeinstall/share/man to your $MANPATH environment variable.

Qt Assistant

If you like to view API documentation with Qt's assistant, then you can generate the necessary 'qch' files using kdedoxyqt.sh.

Note that kdedoxyqt.sh requires doxygen as well as qhelpgenerator from the Qt toolkit.

Warning

doxygen v1.5.7 or above is required.

To use:

% cd source_dir
% /path/trunk/KDE/kdesdk/scripts/kdedoxyqt.sh
[wait]

You should now have a file called apidocs/qch/KDE-4.2.qch in this current working directory. Copy KDE-4.2.qch some place for safe keeping.

Now, start assistant. Go into Edit->Preferences->Documentation and add the safe copy of KDE-4.2.qch into the db.

@@ Line 1: / Line 1: @@
-== Intro ==
+{{Review|
+* Update to kapidox and KF5
+* Update link to community
+}}
 The KDE project uses [http://www.doxygen.org doxygen] to generate API documentation from source code.
@@ Line 8: / Line 12: @@
 ===HTML pages===
 Generate apidox in the KDE format using
-<code>
+<syntaxhighlight lang="text">
 % cd html_dir
 % /path/to/trunk/KDE/kdelibs/doc/api/doxygen.sh --recurse \
      --doxdatadir=/path/to/trunk/KDE/kdelibs/doc/common \
      /path/to/trunk/KDE/kdelibs
-</code>
+</syntaxhighlight>
 Notes:
@@ Line 19: / Line 23: @@
 * You must type the paths in full - the script doesn't understand tilde ('~') representing your home directory.  However, you can use the $HOME environment variable instead.
-* The QTDOCDIR environment variable must first be set to point to the html folder of the Qt documentation.  If QTDIR points to the Qt source directory, there is no need to set QTDOCDIR.
+* The QTDOCDIR environment variable should point to the html folder of the Qt documentation.  If QTDOCDIR is not set, doxygen.sh will try to find the documentation based on the value of QTDIR.
 To generate documentation in {{program|doxygen}} style instead of KDE style, use {{program|kdedoxygen.sh}}:
-<code>
+<syntaxhighlight lang="text">
 % cd source_dir
 % /path/to/trunk/KDE/kdesdk/scripts/kdedoxygen.sh
-</code>
+</syntaxhighlight>
 You'll find the top-level html at {{path|./apidocs/html/index.html}}
@@ Line 37: / Line 41: @@
 Man page lovers can generate man pages using {{program|kdedoxyman.sh}}
 Like so:
-<code>
+<syntaxhighlight lang="text">
 % cd source_dir
 % /path/trunk/KDE/kdesdk/scripts/kdedoxyman.sh -d /path/kdeinstall/share
-</code>
+</syntaxhighlight>
 <br>
 You can also generate man pages from Qt source code using {{program|kdedoxyman.sh}}:
-<code>
+<syntaxhighlight lang="text">
 % cd qt-copy/src
 % /path/trunk/KDE/kdesdk/scripts/kdedoxyman.sh -d /path/kdeinstall/share
-</code>
+</syntaxhighlight>
 <br>
 and then add {{path|/path/kdeinstall/share/man}} to your $MANPATH environment variable.
+===Qt Assistant===
+If you like to view API documentation with Qt's {{program|assistant}}, then you can generate the necessary 'qch' files using {{program|kdedoxyqt.sh}}.
+Note that {{program|kdedoxyqt.sh}} requires {{program|doxygen}} as well as {{program|qhelpgenerator}} from the Qt toolkit.
+{{warning|doxygen v1.5.7 or above is required.}}
+To use:
+<pre>
+% cd source_dir
+% /path/trunk/KDE/kdesdk/scripts/kdedoxyqt.sh
+[wait]
+</pre>
+You should now have a file called apidocs/qch/KDE-4.2.qch in this current working directory. Copy KDE-4.2.qch some place for safe keeping.
+Now, start {{program|assistant}}.  Go into Edit->Preferences->Documentation
+and add the safe copy of KDE-4.2.qch into the db.