GalSim-developers/GalSim — pull request #253 by barnabytprowe (2012-09-19 11:06:20+00:00)
Title: #236 - A Galsim Quick Reference guide and multiple improvements / additions to Python docstrings

Hi all,

This is a pull request that is basically documentation focused. It includes:

1. A GalSim Quick Reference Guide -- a 12 page introduction document in the repo as a pdf in doc/, with the latex source in doc/ref/. The document is hyperlinked to the online GalSim doxygen... where possible (see below)

2. Python docstrings for `angle.py`, `bounds.py` and `position.py`... These were basically missing, which became clear in writing the guide!

3. Various fixes to other small pieces of dox to improve their markup appearance in the GalSim documentation via doxygen. All these changes are using 1.8.X series doxygen, which I'm rather starting to think we should recommend. It's freely available, it's what we use on jenkins, and otherwise it's quite easy to install from their website.

There is one issue that came up which is *not* fixed on this branch, and for which I propose to open a separate issue. The problem is that a number of our python modules are actually defined as classes in `galsim/_galsim.so` and we add things like docstrings and extra methods later. Examples are the classes in...

* `image.py`
* `bounds.py`
* `angle.py`
* `random.py`
* `position.py`

To get these into doxygen (which I think we want to do) we need to find a way to bring their actual class definition into the Python layer, perhaps by inheriting from or containing the current wrapped C++ classes. There was a bit of discussion of this in #236. Whatever changes we make to these classes in Python, we should update the GalSim Quick Ref to include the hyperlinks that will subsequently become available to doxygen-ized docstrings.

Anyway, thanks for all the comments so far on the Guide, more welcomed / encouraged, and please just edit directly for blatant typos / errors!