Documentation

[msimet]

Hi guys--I told @timeifler a while back that I'd set up automatic documentation, and I finally did that. It's on the branch called called documentation. I thought I'd describe here what I've done so far and what still needs to be done.

First, I used the automatic documentation generation tool doxygen. This will parse files of all kinds to create docs, but it was made originally for C/C++ and so it seemed a good idea for this project. doxygen is a program you will need to install; I've also set it up to make interesting dependency graphs, so you'll need to have GraphViz installed too.

To generate the documentation, go to the directory called doc and run doxygen cosmolike_core.cfg. I'd suggest redirecting stdout and stderr to files so you can examine them at your leisure--doxygen dumps out a lot of info. Right now, it makes an html version only, but it can make several other kinds of output (including latex) if you'd like to do that later.

The stuff on the index page is controlled by the comment block in doc/introduction.dox. I just put some placeholder text/structural commands in there so edit at will.

The bulk of the documentation is parsing comment blocks from the .c, .h, and .py files in theory/ which seemed to be the CosmoLike part of the code. If there are no comment blocks it just reads the structure of the call signature. Here's the page describing special commands you can put in the comment blocks to make them work better. A list of uncommented items will go to stderr if you run the doxygen command. Doxygen requires that the files themselves be documented with a little line that says what the file is and, optionally, gives a description; I put one of those lines in the .py and .h files. We don't need them in the .c files as long as everything in .c that you want documented is referenced in .h. Right now a bunch of stuff is undocumented so the documentation page will only have input signatures; you can add documentation either to the header files or to the sources files, as you prefer. doxygen can format code blocks and latex-style formulas if they're helpful in the documentation. If you want an example of what this looks like in practice, the header files in the GalSim directory include/galsim/ are documented with doxygen syntax, and I would just use that as a template.

I'm happy to advise on how to get any of this done if you'd still like to go this route; as it is, at least it's set up for you to play with!