Documentation Guidelines¶
Once you have successfully programmed an entirely working plug-in or module, you may be willing to help others who will look into your code, searching for drops of knowledge and smart tips to reach the application goals. At this point, a documentation can become the lighthouse in the raging wild ocean of your code.
As you can suspect, we actually can not force you to choose a documentation solution over another one, or even force you to create a documentation, however, we if you are ready to do so, we can provide you with some enlightment on how we proceed on our own. We think a more unified help is less destabilizing for the new-comers and also much appreciated by the regular users.
Sphinx¶
Formerly written with Docbook, the current documentation has been entirely remanied in order to ease the whole documentation redaction process, using a more friendly and understandable base syntax with the Sphinx Documentation Generator.
Sphinx is a free tool using the python programming language. The output format can be in HTML or in pdf (among others) offering the possibility to generate off- and online documentation at the same time.
The generator manages the cross-references and link building processes automatically, creating tree of content, download links or image integration in a blink of an eye. The whole generated documentation can then be customize using a standard css file.
Installation¶
All the steps you needed to follow for installing the tool are described on the Sphinx project official website.
The entire process is trivial, however, you will need a python interpreter in order to use the tool.
If you ever encounter any bug or problem, please pass through the Sphinx channels to get the appropriate assistance.
Create a new documentation¶
Sphinx proposes a very helpful script called sphinx-quickstart creating everything you need to begin your documentation. Here again, the Sphinx website, and especially the First Steps with Sphinx section is more than qualified to give you the proper explanations.
Doxygen¶
Doxygen is a documentation system for several languages like C++. It can generate an on-line documentation browser (in HTML), a set of manpages, an off-line reference manual (in LaTeX) and/or others from the set of documented source files of your project. This kind of documentation is a necessary tool for developers to find information about the code. It is not a way to explain how it is implemented but which possibilities you have. Doxygen is available for the most common OS and distributions like Windows, MacOs, Debian, Gentoo…
Installation¶
Being widely used, there is a good chance Doxygen is already installed on your system if you are using a Unix/Linux OS. If the tool is not present, you can follow the steps described in the installation page of the Doxygen website.
For the Tulip project, two distinct documentations are generated. One is destinated for the Developer team and this other one is for the user of the librairies. The Configuration files are generated by the Makefile processing.
Create a new documentation¶
Before starting using Doxygen, you must have a project you want to document. The source code should be commented using the special comment blocks recognizable by Doxygen.
Once you have written the appropriate comments, you will only need to create the configuration file and run Doxygen to generate the documents. Those steps are detailled on this page.
Doxygen FAQ¶
- How to insert a block of code ?
To illustrate your documentation, you can insert a block of code in a description between code and endcode. This code is written in the documentation with highlighting syntax.
- How to force an end of line ?
Use the tag n.
- How to make doxygen ignore code fragment ?
It exists two ways to resolve this questions. The first one is to use the tags cond and endcond to skip the internal code. The second way is to use the preprocessor of Doxygen. In the configuration file, you specify the macros and you verify if the value of PREPROCESSING is to yes. Then, you set MACROS_NAME to PREDEFINED.
#ifndef MACROS_NAME
/* code that must be skipped by Doxygen */
#endif /* MACROS_NAME */
Two macros are defines for Tulip documentations.
- DOXYGEN_NOTFOR_DEVEL : use to skip the code for Developer and User documentations.
- DOXYGEN_NOTFOR_USER : use just for the User documentation.
- How to insert an equation ?
See the appropriate section in the Doxygen website. Doxygen allows you to put Latex formulas in the ouput (just for HTML and latex format). Three ways are avaible. If you want to include formulas in-text, you have to put formulas between a pair of f$
\f$ AB = \sqrt{BC^2 + CA^2} \f$
The second way is for a centered display on a seperate line. These formulas should be put between
\f[
and
\f]
commands.
The third way is to used formulas or other latex elements that are not in a math environment. It can be specified using
\f{environment}
where environment is the latex environment, the corresponding end commands is
\f}