Writing documentation

A guide why and how to write documentation.

Why write documentation?

Code documentation is essential for its future. MoFEM will live only if others know how to use it. It is believed that not necessary the best code will survive but that one with the best documentation. Because all of that always document what you are doing in MoFEM.

About writing manual

Building manual

It is simple; you execute command in your shell,

make doc

Now you can see documentation in web-browser, by opening file


Writing documents, technical aspect

Follow Doxygen http://www.stack.nl/~dimitri/doxygen/index.html to write your documentation files. Another option is Markdown which is supported by Doxygen http://www.stack.nl/~dimitri/doxygen/manual/markdown.html. Before you start you can look how existing documentation is written and follow that example.


Publishing figures with documentation need additional effort. All figures linked in your documentation have to be copied into documentation directory created by Doxygen.

# copy dox/figures to html directory created by doxygen
${CMAKE_COMMAND} -E copy_directory
${PROJECT_SOURCE_DIR}/users_modules/homogenisation/doc/figures ${PROJECT_BINARY_DIR}/html
add_dependencies(doc doxygen_copy_MY_USER_MODUL_figures)

where MY_USER_MODUL is substituted by the name of the module. This cmake script copies files from module doc/figures directory to main documentation directory. Look to existing modules for examples.

Each module can copy figures to a directory with the unique name for USER_MODULE_figures.
\image html application.jpg width=600px

More details about including images are here http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdimage

![Caption text](img.jpg)
![Caption text](img.jpg "Image title")
![Caption text][img def]
![img def]
[img def]: img.jpg "Optional Title"

you can use also link an image

![Caption text](@ref image.png)
![img def]
[img def]: @ref image.png "Caption text"

More details about linking images in Markdown are here http://www.stack.nl/~dimitri/doxygen/manual/markdown.html#md_images