SimGrid
3.13
Versatile Simulation of Distributed Systems
|
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.
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 possible.
First declare your sub-module in the corresponding (project)/doc/doxygen/module-(englobingmodule).doc Two edits are needed in this file:
- @ref XBT_cunit
/** @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.
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.
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 brief 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.
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 style.
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> @tableofcontents blabla bla @section <short_name_of_section> <title> bliblublo @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 ref 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"
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).
Ahhh, cmake and doxygen. The perfect combo to bitch about life for a whole day...
Edit (project)/tools/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.
If you need to run a command (like fig2dev) to generate your image, edit tools/cmake/GenerateDoc.cmake and add your command to the doc 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 tools/cmake/DefinePackage.cmake.
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 tools/cmake/DefinePackage.cmake so that it lands in the archive distribution. It will also be copied automatically to the documentation.
Our website is generated/exported via orgmode, a tool that we use to facilitate our reproducible research.
Get the sources, and start improving the website now! (There is a README in the repo with more details, but it might be outdated. Contact us if you really want to help.)
git clone git://scm.gforge.inria.fr/simgrid/website.git
Once you've changed the doc, you want to run doxygen to regenerate the html output (and maybe the pdf too). Here is how to do this:
make doc # html documentation make pdf # the result is in doc/latex/simgrid_documentation.pdf
Once you're satisfyied with the result, refreshing the documentation on the web pages is very easy, as shown below. A few permission errors are ok, unfortunately. We should improve things here, but I'm not sure of how. A funny thing is that this make target is also provided in the archives we distribute to the users, but I guess that it's harmless :)
make sync-gforge-doc