doc/doxygen/inside_doxygen.doc

   1 /*!
   2 @page inside_doxygen Documenting SimGrid
   3
   4 \tableofcontents
   5
   6 We use doxygen for our documentation. This tool is sometimes anoying
   7 but that's the best we've found so far. Remember, we all bitch about
   8 doxygen, but at the end of the day, it kinda delivers what we need. So
   9 stop bitching about the doc or the tools, and start improving the
  10 documentation text itself.
  11
  12 Good documentation is rare and there is not much project of which we
  13 can get inspiration. The best exception I know is TikZ and
  14 latex-beamer. I'd be so happy if SimGrid documentation could follow
  15 the organisation (and reach half the quality) of the TikZ one. But
  16 anyway. As they say: Documentation is like sex; when it's not good
  17 it's still better than nothing and when it's good it's very very good.
  18
  19 \section inside_doxygen_module Adding a new module to the reference guide
  20
  21 If you add a new file to the project, you want to document it. It's
  22 more urgent if it's user-visible, but it should be done in any case if
  23 possible.
  24
  25 \subsection inside_doxygen_module_create Declaring the module to doxygen
  26
  27 First declare your sub-module in the corresponding
  28 (project)/doc/doxygen/module-(englobingmodule).doc Two edits are
  29 needed in this file:
  30
  31 @li Most of the englobing modules (xbt, msg, sd, etc) have a manually
  32     maintained table of contents as content of the module main page,
  33     at the top of the corresponding file. You want to add a reference to
  34     your submodule there. For that, simply add something like the
  35     following. The dash (-) will help building item lists. The ref
  36     command requests for a link to your module, that is identified
  37     with the word after that (here, I used xbt_cunit as a submodule
  38     identifier.
  39 @verbatim
  40  - @ref XBT_cunit
  41 @endverbatim
  42
  43 @li Create your module below in the file as follows. the first world
  44 after the defgroup keyword must be the submodule identifier you used
  45 above.
  46 @verbatim
  47      /** @defgroup XBT_cunit Unit testing support */
  48 @endverbatim
  49 Warning, the location of this block decides where it appears in the
  50 documentation. In particular, the order of the defgroups is not
  51 inocuitous at all.
  52
  53 \subsection inside_doxygen_module_populate Adding symbols to your module
  54
  55 Once your group is created and referenced from the group containing
  56 it, you must populate it. For that, edit the corresponding header file
  57 to add something like this near the top.
  58 @verbatim
  59 /** @addtogroup XBT_cunit
  60   * @brief <write here a one-line description of your module>
  61   *
  62   * <Write here an introduction to your module>
  63   *
  64   * @{
  65   */
  66
  67 <all the C declarations of your module>
  68
  69 /** @} */
  70 @endverbatim
  71
  72 Any informative stuff is welcomed in the module introduction, on top.
  73 This includes examples that the users can copy/paste to fit their
  74 needs. If your module is too large to be nicely documented on one
  75 unique page, you may want to split its documentation in submodules.
  76 See dynar.h for an example of how to do so.
  77
  78 Make sure to only include the public declarations of your module. For
  79 example, if you have black magic macro voodoo, you probably have some
  80 symbols that are there only for the compiler, but that the users
  81 should not see. In this case, do not put the symbols you want to hide
  82 between the @ { and @ } markers.
  83
  84 \subsection inside_doxygen_module_document Documenting the symbols of your module
  85
  86 Finally, you naturally need to actually write the documentation of
  87 each public symbol belonging to your module. Macros must naturally be
  88 documented in the header file, but it is prefered to put the
  89 documentation in the source file, alongside with the actual
  90 implementation. It is expected that when the code changes, the chances
  91 to update the doc accordingly are higher if the documentation is near
  92 to the code.
  93
  94 For each symbol, you must provide a one-line description in the
  95 <i>brief</i> doxygen parameter. Please document any non trivial
  96 parameter (but something like "dynar: the provided dynar" is not
  97 considered as an informative documentation and can be omitted), and
  98 give any information you feel useful to the user. In particular, add
  99 links to any other location of the documentation that could provide
 100 interesting additional informations.
 101
 102 \section inside_doxygen_page Adding a new page to the user guide
 103
 104 Note that doxygen provides two hierarchies that cannot be intermixed.
 105 Groups are used to build a reference guide while pages are used for
 106 any other kind of page in the documentation. A module cannot contain
 107 any page, while a page cannot contain any module. That's the doxygen
 108 style.
 109
 110 \subsection inside_doxygen_page_write Writing a new documentation page
 111
 112 The first thing to do to add a new page is to actually write a file
 113 containing the information you want to add. It should be located in
 114 (project)/doc/doxygen and be named (something).doc Its content must be
 115 something like the following:
 116
 117 @verbatim
 118 /** @page <short_name> <title>
 119
 120 @tableofcontents
 121
 122 blabla bla
 123
 124 @section <short_name_of_section> <title>
 125
 126 bliblublo
 127
 128 @subsection <short_name_of_subsection> <title>
 129
 130 Even more stuff. Because we love documentation. We all do.
 131
 132 */
 133 @endverbatim
 134
 135 Don't forget the starting and ending comment signs. Doxygen only takes
 136 documentation that is in comments, even if there is nothing else in
 137 the file.
 138
 139 Any short names must be uniq as they are used for the <i>ref</i>
 140 commands to build references between parts.
 141
 142 Titles should be chosed wisely, as they are used (1) as section
 143 headers (2) in the table of contents (3) as text of references, unless
 144 people building a reference specify a replacement text as in:
 145 @verbatim
 146 @ref shortname "text to use instead of the title"
 147 @endverbatim
 148
 149 \subsection inside_doxygen_page_doxy Registering a documentation page to doxygen
 150
 151 Edit (project)/doc/Doxyfile.in and add your page to the INPUT
 152 variable. Don't edit the Doxyfile directly, as it is generated
 153 automatically from the Doxyfile.in: your changes would be overwritten.
 154
 155 Also, edit the source file of the page that will englob the newly page
 156 (to add a new page at root level, edit index.doc that declares the
 157 root), and add something like the following.
 158
 159 @verbatim
 160 @subpage <shortname>
 161 @endverbatim
 162
 163 This allows doxygen to understand about the page hierarchy that you
 164 want to build. It also puts the name of the subpage as a ref would do.
 165 That is why every page in our documentation seem to contain a table of
 166 contents of sub pages even if it dupplicates what's on the left.
 167 That's the doxygen style (but I can live with it).
 168
 169 \subsection inside_doxygen_page_cmake Registering a documentation page to cmake
 170
 171 Ahhh, cmake and doxygen. The perfect combo to bitch about life for a
 172 whole day...
 173
 174 Edit (project)/buildtools/Cmake/DefinePackage.cmake, and add your
 175 newly added page to the DOC_SOURCES. And bitch about these damn tools.
 176
 177 Don't forget to commit your page, so that you can get some git fun to
 178 complete your day.
 179
 180 \section inside_doxygen_image Adding an image to the documentation
 181
 182 If you need to run a command (like fig2dev) to generate your image,
 183 edit buildtools/Cmake/GenerateDoc.cmake and add your command to the
 184 simgrid_documentation target (grep for fig2dev in the file to see
 185 where exactly). Don't forget to add the source of your image to the
 186 archive somehow. You can add it to the list DOC_FIG of
 187 buildtools/Cmake/DefinePackage.cmake.
 188
 189 If your image is ready to use, put your png in doc/webcruft, and
 190 register it to cmake by adding it to the DOC_IMG list of file
 191 buildtools/Cmake/DefinePackage.cmake so that it lands in the archive
 192 distribution. It will also be copied automatically to the documentation.
 193
 194 \section inside_doxygen_website Working on the website
 195
 196 Actually, the website is very different from doxygen. It uses a tool
 197 called jekyll to turn markup-formated text into nice static web pages.
 198 Jekyll is less annoying than doxygen since it's written in a scripting
 199 language: you can dynamically add (or change) parts of the tool to
 200 make it fit your needs. Get the sources, and start improving the
 201 website now (there is a README in the repo with more details).
 202
 203 @verbatim
 204 git clone git://scm.gforge.inria.fr/simgrid/website.git
 205 @endverbatim
 206
 207 \section inside_doxygen_regen Regenerating the documentation
 208
 209 Once you've changed the doc, you want to run doxygen to regenerate the
 210 html output (and maybe the pdf too). Here is how to do this:
 211
 212 @verbatim
 213 make simgrid_documentation # html documentation
 214 make pdf # the result is in doc/latex/simgrid_documentation.pdf
 215 @endverbatim
 216
 217 Once you're satisfyied with the result, refreshing the documentation
 218 on the web pages is very easy, as shown below. A few permission errors
 219 are ok, unfortunately. We should improve things here, but I'm not sure
 220 of how. A funny thing is that this make target is also provided in the
 221 archives we distribute to the users, but I guess that it's harmless :)
 222
 223 @verbatim
 224 make sync-gforge-doc
 225 @endverbatim
 226
 227 */