Development/Tools/apidox: Difference between revisions

    From KDE TechBase
    m (Text replace - "<code>" to "<syntaxhighlight lang="text">")
    m (Text replace - "</code>" to "</syntaxhighlight>")
    Line 12: Line 12:
         --doxdatadir=/path/to/trunk/KDE/kdelibs/doc/common \
         --doxdatadir=/path/to/trunk/KDE/kdelibs/doc/common \
         /path/to/trunk/KDE/kdelibs
         /path/to/trunk/KDE/kdelibs
    </code>
    </syntaxhighlight>


    Notes:
    Notes:
    Line 24: Line 24:
    % cd source_dir
    % cd source_dir
    % /path/to/trunk/KDE/kdesdk/scripts/kdedoxygen.sh
    % /path/to/trunk/KDE/kdesdk/scripts/kdedoxygen.sh
    </code>
    </syntaxhighlight>


    You'll find the top-level html at {{path|./apidocs/html/index.html}}
    You'll find the top-level html at {{path|./apidocs/html/index.html}}
    Line 39: Line 39:
    % cd source_dir
    % cd source_dir
    % /path/trunk/KDE/kdesdk/scripts/kdedoxyman.sh -d /path/kdeinstall/share
    % /path/trunk/KDE/kdesdk/scripts/kdedoxyman.sh -d /path/kdeinstall/share
    </code>
    </syntaxhighlight>
    <br>
    <br>
    You can also generate man pages from Qt source code using {{program|kdedoxyman.sh}}:
    You can also generate man pages from Qt source code using {{program|kdedoxyman.sh}}:
    Line 45: Line 45:
    % cd qt-copy/src
    % cd qt-copy/src
    % /path/trunk/KDE/kdesdk/scripts/kdedoxyman.sh -d /path/kdeinstall/share
    % /path/trunk/KDE/kdesdk/scripts/kdedoxyman.sh -d /path/kdeinstall/share
    </code>
    </syntaxhighlight>
    <br>
    <br>
    and then add {{path|/path/kdeinstall/share/man}} to your $MANPATH environment variable.
    and then add {{path|/path/kdeinstall/share/man}} to your $MANPATH environment variable.

    Revision as of 20:50, 29 June 2011

    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.