v0.9.0
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 necessarily the best code will survive but that one with the best documentation. Therefore, you should always document always document what you are doing in MoFEM.

  • Good documentation helps to revise your code
  • Help others to understand what you are doing
  • Report assumptions, limitations and bugs in your code
  • Think about different kinds of users, f.e. end-user who only executess code, beginner programmers and advanced developers
  • Link different parts of your work in modules
  • Follow http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html
  • Think about yourself; you might forget. Documentation helps to remind what you have done

About writing manual

  • If possible, make it instructive, step by step
  • Try to use examples which others can follow
  • First, you need to ask yourself who you’re writing for. At first, you generally need to appeal to two audiences: Developers or Users.
  • In the first paragraph indicate to whom you write this documentation what is proposed if it
  • Try to indicate a level of difficulty.
  • User references to another part of documentation if applicable
  • Use latex formulas to place your equations.
  • Use links to other sources on the internet, f.e. Wikipedia

Building manual

It is simple; you execute command in your shell,

make doc

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

$MOFEM_DIR/htm/index.html

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.

  • A useful list of command in Doxygen http://www.stack.nl/~dimitri/doxygen/manual/commands.html
  • If you write general documentation about MoFEM, you locate your files in /doc/user_guide.
  • If your documentation is about MoFEM and written in Markdown, locate it in /doc/markdown
  • If documentation is about some user module, then place documentation files in user module directory, f.e. users_modules/nonlinear_elasticity/doc

Figures

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

  • If you write documentation about the use of MoFEM library, this is straightforward, you simply copy your figures to doc/figures. CMake will do a job for you, and copy files with figures to appropriate directory.
  • If you write user module documentation, you do it like above, only difference, you place you figure in directory user_modules/my_user_module/doc/figures. Note that each documentation directory should consist file AddDocumentation.cmake:
# copy dox/figures to html directory created by doxygen
add_custom_target(doxygen_copy_MY_USER_MODULE_figures
${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.

Todo:
Each module can copy figures to a directory with the unique name for USER_MODULE_figures.
  • It is critical that name of your figure file is unique. All figures (or any other linked files) are copied to the same directory ${PROJECT_BINARY_DIR}/html while Doxygen creates documentation. It is advised to use convention name_figure1.png, where name is the name of the module.
  • Including figure in case of Doxygen document:
\image html application.jpg width=600px

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

  • Including figure in case of Markdown documentation
![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