Documentation

Wiki documentation

We encourage all developers to also contribute to the documentation. The documentation is part of the GitLab repository (you are reading it right now). Here are some general information on the Gitlab Wiki documentation.

General structure of the ProDiMo wiki

The wiki has some structure which is also reflected in the directory structure. There are three main parts:

Installation and compilation of ProDiMo and related tools (idl, prodimopy)

  • User Guide (Directory: userguide/) Detailed information on how to use ProDiMo, in particular all the different modes and parameter options.

  • Developer Guide (Directory: devguide/)

Information for developers working on ProDiMo, including code structure and contribution/GIT guidelines etc.

If you are creating a new wiki page, please think about where it fits best in this structure. If you create the page on GitLab (with the wiki editor), prepend the directory name to the page name. For examples a page with the name/title getstarted/somenewfeature will end up in the getstarted directory and the file name will be somenewfeature.md.

This structure is fixed, so please do not create some new directory. If you think it is required, please coordinate with the main developers.

Linking files and images

  • Images should be in the uploadsdirectory. If you want to link them and you edit a document in a subdirectory, use ../uploads/imagename.png.
  • to link to a document in the same directory use ./documentname, without the .md extension.
  • to link to a document in another directory use ../dirname/documentname, without the .md extension.
  • try to avoid links such as somedocument or directory/somedocument as this means the root of the wiki, and might not work in both the Gitlab wiki and the readthedocs versions. So the best is to always use ./ or ../dirname/.

References

It is good to provide references to papers where it is useful (not just ProDiMo papers). Please just use a link to the ads entry, like this:

[Woitke+ 2009](https://ui.adsabs.harvard.edu/abs/2009A%26A...501..383W/abstract)

This way we might have the change to e.g. find all references to papers in the documentation.

Images

To included images we recommend to use something like that:

<img src="../uploads/imagename.png" alt="Some Image" width="50%"/>

Although, this is not a markdown standard it is commonly used, and allows to show images in a flexible way by using width=50%.

Offline editing of the wiki

It is fine to edit the wiki pages directly on GitLab, however, for larger changes (or in general), editing it offline with your favourite markdown editor might be more comfortable. As the wiki pages are a git repository itself you can clone it make changes, branches etc. and push it back to GitLab when you are ready. How to clone the wiki and to view/edit it offline is described in Offline access to the wiki.

The readthedocs version of the wiki

The ProDiMo wiki is also published on readthedocs: ProDiMo Wiki. Which means it is also accessible outside of GitLab (so from everywhere).

To make this work, we require an additional public repository, which is just a clone of the prodimo.wiki git repository. With the current free GitLab version used at Kapteyn, it is not possible to make just the prodimo.wiki public, but not the main prodimo repository. Unfortunately, an automatic cloning of the wiki repository within GitLab also does not work. Hence, this needs to be done "manually", at the moment, which means that changes in the wiki will not appear immediately on the readthedocs version!

Currently, the clone repository is synced daily via the automatic tests, hence changes you made in the documentation will only appear a day later on the readthedocs version.

Syncing the origin and clone repository

If you want to set up the sync manually, the following steps are required. Please note that to actually do the syncing, you need to have he proper credentials (e.g., maintainer) to be able to push to the clone repository.

  • Clone the prodimo.wiki repository (only once, adapt the user)

    git clone https://USER.NAME@gitlab.astro.rug.nl/prodimo/prodimo.wiki.git
cd prodimo.wiki
git config credential.helper store 
git config pull.rebase true
git config pull.merge false 
git config pull.ff only

    Depending on your local git configuration, you might have to make a new API Token.

  • add a new remote for the clone repository which is also in the gitlab server (only once)

    git remote add clone https://USER.NAME@gitlab.astro.rug.nl/prodimo/prodimowikiclone.git

  • whenever the repositories should be synchronized, do the following:

    git pull origin
git push clone

Building the documentation with mkdocs

The readthedocs version of the wiki is a pure html built of the whole ProDiMo wiki. To achieve this, we use mkdocs. If you are only editing some wiki pages on GitLab you do not have to worry about this at all. If you want to make more comprehensive changes and test them locally, you can also build the entire documentation locally.

As mentioned above, you need to first clone the ProDiMo wiki repository. Then change into the prodimo.wiki directory (that is the directory name if you have not chosen another one). In this directory, you will find some files which are required for mkdocs (e.g., mkdocs.yml). There is also a build script mkbuild.sh, which we will use to build the documentation (i.e., convert the md file to html).

At first, you need to install a couple of Python packages. We recommend doing this in a Python virtual or conda environment. For conda, you can do it in a terminal:

conda create -n prodimowiki python=3.13
conda activate prodimowiki
pip install -r requirements.txt

The last command installs all required Python packages (including mkdocs) with the correct version (i.e., the same as on readthedocs). Currently, we are using Python 3.13.x for the mkdocs build and on readthedocs.

After that, you should be able to build the documentation with:

./mkbuild.sh

There will be a lot of screen output, and you will also see some warnings. Anyway, there should not be an error message. If it worked, the generated html documentation can be found in the html directory. Simply open the index.html file in a browser and enjoy the documentation.

WARNING: Please do not change configuration files such as the mkdocs.yml or the mkbuild.sh, as those are also used on readthedocs. If you think some changes are required, please contact Ch. Rab.

As noted already, this is still experimental, but let us know if you find it useful, or if you have any suggestions for improvements, or if you have any problems building the mkdocs wiki.

Potential problems

To show LaTeX math expressions, mkdocs uses KaTeX. There can be problems if, for example, you have already installed some version of Katex. If this is the case, you might see an error message mentioning katex. However, if you are using conda, simply installing katex in the prodimowiki conda environment should do the trick (i.e., conda install katex).

Doxygen

From their website: [http://www.doxygen.nl/]

"Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D."

Installation

First, follow the instructions on [http://www.doxygen.nl/] to download and install Doxygen on your system. We tested it on Linux and MacOS X. The easiest way to install it on Linux or Mac OS is likely via conda. Just do:

conda install -c conda-forge doxygen
conda install -c conda-forge graphviz
````

With `graphviz` the `dot` program is installed as well, which is required to generate e.g. call graphs. 

### Generating the source documentation

You will not find a lot of inline source documentation that is compatible with Doxygen in the <span class="smallcaps">ProDiMo</span> code, but one useful feature is the automatic generation of call-graphs. So if you want to understand the code structure better, generating the documentation with Doxygen is a good idea. Here is an example of such a call graph: 

![Example Call Graph](../uploads/escape_callgraph.png "Title")

To generate the documentation go to `src_develop/`, and you will find a file called `Doxyfile`, which is a configuration file used by Doxygen
The calling is (on the linux/Mac prompt):

```console
doxygen Doxyfile

The current configuration file will put the output in a ../docs/ directory, and will only generate the html format. Just open docs/html/index.html with your browser to see the documentation.

If you also want the latex output (to generate a pdf file), you have to set GENERATE_LATEX = YES in the Doxyfile. To generate a pdf file from the latex source, you have to have a latex installation on your system (e.g. TeX Live). If that is the case, go to docs/latex directory and type make. After a moment, a pdf file (refman.pdf) is available.