From a8ba146044f5e596efd93d81efd2958cbb1cb3b1 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sat, 8 Dec 2012 04:18:31 +0100 Subject: [PATCH 1/1] document how to document simgrid so that other can do that too --- doc/Doxyfile.in | 1 + doc/doxygen/inside_doxygen.doc | 208 +++++++++++++++++++++++++++++++++ doc/doxygen/internals.doc | 1 + 3 files changed, 210 insertions(+) create mode 100644 doc/doxygen/inside_doxygen.doc diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 17ade966a7..c338135674 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -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 index 0000000000..b9594619f0 --- /dev/null +++ b/doc/doxygen/inside_doxygen.doc @@ -0,0 +1,208 @@ +/*! +@page inside_doxygen Documenting SimGrid + +\tableofcontents + +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 +possible. + +\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. +@verbatim + - @ref XBT_cunit +@endverbatim + +@li Create your module below in the file as follows. the first world +after the defgroup keyword must be the submodule identifier you used +above. +@verbatim + /** @defgroup XBT_cunit Unit testing support */ +@endverbatim +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. +@verbatim +/** @addtogroup XBT_cunit + * @brief + * + * + * + * @{ + */ + + + +/** @} */ +@endverbatim + +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 +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. + +\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 +style. + +\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: + +@verbatim +/** @page + +@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. + +*/ +@endverbatim + +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: +@verbatim +@ref shortname "text to use instead of the title" +@endverbatim + +\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. + +@verbatim +@subpage <shortname> +@endverbatim + +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 +buildtools/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 +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). + +@verbatim +git clone git://scm.gforge.inria.fr/simgrid/website.git +@endverbatim + + +*/ diff --git a/doc/doxygen/internals.doc b/doc/doxygen/internals.doc index 3c6234927e..08a2ee1375 100644 --- a/doc/doxygen/internals.doc +++ b/doc/doxygen/internals.doc @@ -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 -- 2.20.1