doxygen_usage.doc 4.62 KB
Newer Older
Dimitri van Heesch's avatar
Dimitri van Heesch committed
1 2
/******************************************************************************
 *
3
 * 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
4
 *
Dimitri van Heesch's avatar
Dimitri van Heesch committed
5
 * Copyright (C) 1997-2013 by Dimitri van Heesch.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
6 7 8 9 10 11 12
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation under the terms of the GNU General Public License is hereby 
 * granted. No representations are made about the suitability of this software 
 * for any purpose. It is provided "as is" without express or implied warranty.
 * See the GNU General Public License for more details.
 *
Dimitri van Heesch's avatar
Dimitri van Heesch committed
13 14
 * Documents produced by Doxygen are derivative works derived from the
 * input used in their production; they are not affected by this license.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
15 16 17 18 19
 *
 */
/*! \page doxygen_usage Doxygen usage

Doxygen is a command line based utility.  Calling \c doxygen with the
Dimitri van Heesch's avatar
Dimitri van Heesch committed
20
\c --help option at the command line will give you a brief description of the 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
21 22 23
usage of the program.

All options consist of a leading character <tt>-</tt>, 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
24
followed by one character and one or more arguments depending on the option.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
25

Dimitri van Heesch's avatar
Dimitri van Heesch committed
26 27
To generate a manual for your project you typically 
need to follow these steps:
Dimitri van Heesch's avatar
Dimitri van Heesch committed
28 29
<ol>
<li> You document your source code with 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
30
     special documentation blocks (see section \ref specialblock).
Dimitri van Heesch's avatar
Dimitri van Heesch committed
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
<li> You generate a configuration file (see section \ref config) by 
     calling doxygen with the \c -g option:
\verbatim
doxygen -g <config_file>
\endverbatim
<li> You edit the configuration file so it matches your project.
     In the configuration file you can specify the input files and
     a lot of optional information.
<li> You let doxygen generate the documentation, based on the settings in the
     configuration file:
\verbatim
doxygen <config_file>
\endverbatim
</ol>

Dimitri van Heesch's avatar
Dimitri van Heesch committed
46
If you have a configuration file generated with an older version of
Dimitri van Heesch's avatar
Dimitri van Heesch committed
47
doxygen, you can upgrade it to the current version by running doxygen
Dimitri van Heesch's avatar
Dimitri van Heesch committed
48 49 50 51
with the -u option.
\verbatim
doxygen -u <config_file>
\endverbatim
52
All configuration settings in the original configuration file will be copied
Dimitri van Heesch's avatar
Dimitri van Heesch committed
53 54 55 56
to the new configuration file. Any new options will have their default value.
Note that comments that you may have added in the original configuration file 
will be lost.

57
\section doxygen_finetune Fine-tuning the output
Dimitri van Heesch's avatar
Dimitri van Heesch committed
58 59 60 61 62 63 64 65 66 67
If you want to fine-tune the way the output looks, doxygen allows you 
generate default style sheet, header, and footer files that you can edit
afterwards:
<ul>
<li>For HTML output, you can generate the default header file 
    (see \ref cfg_html_header "HTML_HEADER"), the default footer 
    (see \ref cfg_html_footer "HTML_FOOTER"), and the default style
    sheet (see \ref cfg_html_stylesheet "HTML_STYLESHEET"), using the
    following command:
\verbatim
68
doxygen -w html header.html footer.html stylesheet.css <config_file>
Dimitri van Heesch's avatar
Dimitri van Heesch committed
69
\endverbatim
70 71
  The `config_file` is optional. When omitted doxygen will search for 
  a file named `Doxyfile` and process that. When this is also not found it
72 73
  will used the default settings.

74
<li>For \f$\mbox{\LaTeX}\f$ output, you can generate the first and last part of \c refman.tex 
75 76 77 78
    (see \ref cfg_latex_header "LATEX_HEADER" and
     \ref cfg_latex_footer "LATEX_FOOTER") and the style sheet included
    by that header (normally <code>doxygen.sty</code>), using the following
    command:
Dimitri van Heesch's avatar
Dimitri van Heesch committed
79
\verbatim
80
doxygen -w latex header.tex footer.tex doxygen.sty <config_file>
Dimitri van Heesch's avatar
Dimitri van Heesch committed
81
\endverbatim
82
If you need non-default options (for instance to use extra \f$\mbox{\LaTeX}\f$ packages) 
83 84 85 86
you need to make a config file with those options set correctly and then specify
that config file after the generated files (make a backup of the configuration
file first so you don't loose it in case you forget to specify one of the 
output files).
Dimitri van Heesch's avatar
Dimitri van Heesch committed
87 88 89 90 91 92
<li>For RTF output, you can generate the default style sheet file (see
    \ref cfg_rtf_stylesheet_file "RTF_STYLESHEET_FILE") using:
\verbatim
doxygen -w rtf rtfstyle.cfg
\endverbatim
</ul>
93 94 95 96
\warning When using a custom header you are responsible 
  for the proper inclusion of any scripts and style sheets that doxygen 
  needs, which is dependent on the configuration options and may changes
  when upgrading to a new doxygen release.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
97

98
\note
99
<ul>
Dimitri van Heesch's avatar
Dimitri van Heesch committed
100 101 102 103
<li> If you do not want documentation for each item inside the configuration
     file then you can use the optional \c -s option. This can use be
     used in combination with the \c -u option, to add or strip the
     documentation from an existing configuration file.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
104
     Please use the \c -s option if you send me a configuration file 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
105
     as part of a bug report!
106 107 108
<li> To make doxygen read/write to standard input/output instead of from/to 
     a file, use \c - for the file name.
</ul>
109

110 111 112 113 114 115

\htmlonly
Go to the <a href="doxywizard_usage.html">next</a> section or return to the
 <a href="index.html">index</a>.
\endhtmlonly

Dimitri van Heesch's avatar
Dimitri van Heesch committed
116
*/