A guide to 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 the one with the best documentation. Therefore, you should always document what you are doing in MoFEM.
Good documentation helps to:
- Revise your code
- Make others understand what you are doing
- Report assumptions, limitations and bugs in your code
- Link different parts of your work in modules
Think about different kinds of users:
- End-users who only execute the code
- Beginner programmers
- Advanced developers
- Yourself; you might forget and documentation helps to remind you what you have done
Follow https://www.doxygen.nl/manual/docblocks.html
About writing a manual
- If possible, make it instructive, step by step
- Try to use examples which others can follow
- In the first paragraph indicate to whom you write this documentation and what the purpose of it is
- Try to indicate a level of difficulty
- Use references to another part of documentation if applicable
- Use latex formulas to place your equations
- Use links to other sources on the internet, e.g. Wikipedia
Building manuals
It is simple; you execute the following command in your shell
Now you can see documentation in web-browser, by opening the file
$MOFEM_DIR/html/index.html
Writing documents, technical aspect
Follow Doxygen https://www.doxygen.nl/index.html to write your documentation files. Another option is Markdown which is supported by Doxygen https://www.doxygen.nl/manual/markdown.html. Before you start, you can look at how existing documentation is written and follow that example.
- A useful list of commands in Doxygen https://www.doxygen.nl/manual/commands.html
- If you write general documentation about MoFEM, 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, e.g. users_modules/nonlinear_elasticity/doc
Figures
Publishing documentation with figures needs 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, it is straightforward. Simply copy your figures to doc/figures. CMake will do the job for you, and copy files with figures to the appropriate directory.
- If you write user module documentation, it is similar. The figures are just placed in the directory user_modules/my_user_module/doc/figures. Note that each documentation directory should contain the 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_MODULE_figures)
where MY_USER_MODULE is substituted by the name of the module. This cmake script copies files from module doc/figures directory to the main documentation directory. Look into 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 https://www.doxygen.nl/manual/commands.html#cmdimage
Including figure in case of Markdown documentation:
![Caption text][img def]
![img def]
[img def]: img.jpg "Optional Title"
you also can use @ref to link an image:
![img def]
[img def]: @ref image.png "Caption text"
More details about linking images in Markdown are here https://www.doxygen.nl/manual/markdown.html#md_images
