X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/deec5652300e252feaed48ce0067f59ca58693bd..8fb46a312e49dbbb5ba41a79364ff0390563c9eb:/doc/doxygen/inside_doxygen.doc diff --git a/doc/doxygen/inside_doxygen.doc b/doc/doxygen/inside_doxygen.doc deleted file mode 100644 index eec1065d69..0000000000 --- a/doc/doxygen/inside_doxygen.doc +++ /dev/null @@ -1,224 +0,0 @@ -/*! -@page inside_doxygen Documenting SimGrid - -@tableofcontents - -We use doxygen for our documentation. It's annoying but that's the -best we've found so far. 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 organization (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-(enclosing module).doc Two edits are -needed in this file: - -@li Most of the enclosing 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 sub-module 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_str as a sub-module - identifier. -@verbatim - - @ref XBT_str -@endverbatim - -@li Create your module below in the file as follows. the first world -after the defgroup keyword must be the sub-module identifier you used -above. -@verbatim - /** @defgroup XBT_str String related functions */ -@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_str - * @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 sub-modules. -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 information. - -@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 - -blah blah blah - -@section <short_name_of_section> <title> - -blah blah blah - -@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)/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. - -@section inside_doxygen_image Adding an image to the documentation - -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. - -@section inside_doxygen_website Working on the website - -Our website is generated/exported via [orgmode](http://www.orgmode.org), 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.) - -@verbatim -git clone git://scm.gforge.inria.fr/simgrid/website.git -@endverbatim - -@section inside_doxygen_regen Regenerating the documentation - -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: - -@verbatim -make doc # html documentation -make pdf # the result is in doc/latex/simgrid_documentation.pdf -@endverbatim - -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. This @c make target is also provided in the archives we -distribute to the users, but I guess that it's harmless :) - -@verbatim -make sync-gforge-doc -@endverbatim - -*/