Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
document how to document simgrid so that other can do that too
authorMartin Quinson <martin.quinson@loria.fr>
Sat, 8 Dec 2012 03:18:31 +0000 (04:18 +0100)
committerMartin Quinson <martin.quinson@loria.fr>
Sat, 8 Dec 2012 03:18:31 +0000 (04:18 +0100)
doc/doxygen/inside_doxygen.doc [new file with mode: 0644]

index 17ade96..c338135 100644 (file)
@@ -671,6 +671,7 @@ INPUT                  = doxygen/index.doc \
                            doxygen/pls.doc \
                            doxygen/bindings.doc \
                           doxygen/internals.doc \
+                            doxygen/inside_doxygen.doc \
                             doxygen/inside_extending.doc \
                             doxygen/inside_cmake.doc \
                             doxygen/inside_autotests.doc \
diff --git a/doc/doxygen/inside_doxygen.doc b/doc/doxygen/inside_doxygen.doc
new file mode 100644 (file)
index 0000000..b959461
--- /dev/null
@@ -0,0 +1,208 @@
+@page inside_doxygen Documenting SimGrid
+We use doxygen for our documentation. This tool is sometimes anoying
+but that's the best we've found so far. Remember, we all bitch about
+doxygen, but at the end of the day, it kinda delivers what we need. So
+stop bitching about the doc or the tools, and start improving the
+documentation text itself.
+Good documentation is rare and there is not much project of which we
+can get inspiration. The best exception I know is TikZ and
+latex-beamer. I'd be so happy if SimGrid documentation could follow
+the organisation (and reach half the quality) of the TikZ one. But
+anyway. As they say: Documentation is like sex; when it's not good
+it's still better than nothing and when it's good it's very very good.
+\section inside_doxygen_module Adding a new module to the reference guide
+If you add a new file to the project, you want to document it. It's
+more urgent if it's user-visible, but it should be done in any case if
+\subsection inside_doxygen_module_create Declaring the module to doxygen
+First declare your sub-module in the corresponding
+(project)/doc/doxygen/module-(englobingmodule).doc Two edits are
+needed in this file: 
+@li Most of the englobing modules (xbt, msg, sd, etc) have a manually
+    maintained table of contents as content of the module main page,
+    at the top of the corresponding file. You want to add a reference to
+    your submodule there. For that, simply add something like the
+    following. The dash (-) will help building item lists. The ref
+    command requests for a link to your module, that is identified
+    with the word after that (here, I used xbt_cunit as a submodule
+    identifier.
+ - @ref XBT_cunit
+@li Create your module below in the file as follows. the first world
+after the defgroup keyword must be the submodule identifier you used
+     /** @defgroup XBT_cunit Unit testing support */
+Warning, the location of this block decides where it appears in the
+documentation. In particular, the order of the defgroups is not
+inocuitous at all.
+\subsection inside_doxygen_module_populate Adding symbols to your module
+Once your group is created and referenced from the group containing
+it, you must populate it. For that, edit the corresponding header file
+to add something like this near the top.
+/** @addtogroup XBT_cunit
+  * @brief <write here a one-line description of your module>
+  *
+  * <Write here an introduction to your module>
+  * 
+  * @{
+  */
+<all the C declarations of your module>
+/** @} */
+Any informative stuff is welcomed in the module introduction, on top.
+This includes examples that the users can copy/paste to fit their
+needs. If your module is too large to be nicely documented on one
+unique page, you may want to split its documentation in submodules.
+See dynar.h for an example of how to do so. 
+Make sure to only include the public declarations of your module. For
+example, if you have black magic macro voodoo, you probably have some
+symbols that are there only for the compiler, but that the users
+should not see. In this case, do not put the symbols you want to hide
+between the @ { and @ } markers.
+\subsection inside_doxygen_module_document Documenting the symbols of your module
+Finally, you naturally need to actually write the documentation of
+each public symbol belonging to your module. Macros must naturally be
+documented in the header file, but it is prefered to put the
+documentation in the source file, alongside with the actual
+implementation. It is expected that when the code changes, the chances
+to update the doc accordingly are higher if the documentation is near
+to the code.
+For each symbol, you must provide a one-line description in the
+<i>brief</i> doxygen parameter. Please document any non trivial
+parameter (but something like "dynar: the provided dynar" is not
+considered as an informative documentation and can be omitted), and
+give any information you feel useful to the user. In particular, add
+links to any other location of the documentation that could provide
+interesting additional informations.
+\section inside_doxygen_page Adding a new page to the user guide
+Note that doxygen provides two hierarchies that cannot be intermixed.
+Groups are used to build a reference guide while pages are used for
+any other kind of page in the documentation. A module cannot contain
+any page, while a page cannot contain any module. That's the doxygen
+\subsection inside_doxygen_page_write Writing a new documentation page
+The first thing to do to add a new page is to actually write a file
+containing the information you want to add. It should be located in
+(project)/doc/doxygen and be named (something).doc Its content must be
+something like the following:
+/** @page <short_name> <title>
+blabla bla
+@section <short_name_of_section> <title>
+@subsection <short_name_of_subsection> <title>
+Even more stuff. Because we love documentation. We all do.
+Don't forget the starting and ending comment signs. Doxygen only takes
+documentation that is in comments, even if there is nothing else in
+the file. 
+Any short names must be uniq as they are used for the <i>ref</i>
+commands to build references between parts.
+Titles should be chosed wisely, as they are used (1) as section
+headers (2) in the table of contents (3) as text of references, unless
+people building a reference specify a replacement text as in:
+@ref shortname "text to use instead of the title"
+\subsection inside_doxygen_page_doxy Registering a documentation page to doxygen
+Edit (project)/doc/Doxyfile.in and add your page to the INPUT
+variable. Don't edit the Doxyfile directly, as it is generated
+automatically from the Doxyfile.in: your changes would be overwritten.
+Also, edit the source file of the page that will englob the newly page
+(to add a new page at root level, edit index.doc that declares the
+root), and add something like the following. 
+@subpage <shortname>
+This allows doxygen to understand about the page hierarchy that you
+want to build. It also puts the name of the subpage as a ref would do.
+That is why every page in our documentation seem to contain a table of
+contents of sub pages even if it dupplicates what's on the left.
+That's the doxygen style (but I can live with it).
+\subsection inside_doxygen_page_cmake Registering a documentation page to cmake
+Ahhh, cmake and doxygen. The perfect combo to bitch about life for a
+whole day...
+Edit (project)/buildtools/Cmake/DefinePackage.cmake, and add your
+newly added page to the DOC_SOURCES. And bitch about these damn tools.
+Don't forget to commit your page, so that you can get some git fun to
+complete your day.
+\section inside_doxygen_image Adding an image to the documentation
+If you need to run a command (like fig2dev) to generate your image,
+edit buildtools/Cmake/GenerateDoc.cmake and add your command to the
+simgrid_documentation target (grep for fig2dev in the file to see
+where exactly). Don't forget to add the source of your image to the
+archive somehow. You can add it to the list DOC_FIG of
+If your image is ready to use, put your png in doc/webcruft, and
+register it to cmake by adding it to the DOC_IMG list of file
+buildtools/Cmake/DefinePackage.cmake so that it lands in the archive
+distribution. It will also be copied automatically to the documentation.
+\section inside_doxygen_website Working on the website
+Actually, the website is very different from doxygen. It uses a tool
+called jekyll to turn markup-formated text into nice static web pages.
+Jekyll is less annoying than doxygen since it's written in a scripting
+language: you can dynamically add (or change) parts of the tool to
+make it fit your needs. Get the sources, and start improving the
+website now (there is a README in the repo with more details).
+git clone git://scm.gforge.inria.fr/simgrid/website.git
index 3c62349..08a2ee1 100644 (file)
@@ -13,6 +13,7 @@ SimGrid project, ie how to extend the framework in any way, how the
 automatic tests are run, and so on. These informations are split on
 several pages, as follows:
+ - @subpage inside_doxygen
  - @subpage inside_extending
  - @subpage inside_cmake
  - @subpage inside_release