GammaLib

I’ll have a look.

BTW: I added an examples directory to GammaLib where I started to add some Python scripts. The idea hear is to have illustrations of GammaLib usage which makes it easier to start with a own development ...

The existing Python examples (in the test and examples folder) are great!
What is missing is having some explanations and links into the API docs and putting them on a web page so that users find them.

Here’s an example of what I think could also work nicely for gammalib and what I’d be happy to help set up / start writing in the next days:
Tutorial: http://scikit-learn.org/stable/modules/tree.html#classification
Example: http://scikit-learn.org/stable/auto_examples/tree/plot_iris.html#example-tree-plot-iris-py
API: http://scikit-learn.org/stable/modules/generated/sklearn.tree.DecisionTreeClassifier.html

In the case of GammaLib the tutorial and examples could be written in RST and processed with Sphinx ... the API would for sure remain Doxygen. The alternative solution is to do everything in Doxygen, but I don’t think it’s as nice.

I checked out your documentation, this looks indeed great! I was looking at some time into technologies for writing documentation, but did not find anything satisfactory. I was at some point thinking of using latex2html (as quite some documentation exists already in Latex), but RST looks also fine.

While reviewing all the method interfaces, I also worked to some extend on the Doxygen documentation and the description of the classes. As example you may check the GModels class. I was thinking of putting such kind of information in for every class, but all these things take just an incredible amount of time.

How about I change the existing html website and tutorial to rst and sphinx and once that is in place we discuss what documentation is most needed.

I think having narrative documentation that explains the most important concepts and classes of the API is much more important and a much smaller task than improving and extending the 80,000 lines of existing, already very good compared to most other projects, docstrings.

I accidentally branched from master and worked with an old version ... please ignore this comment.

Christoph Deil wrote:

How about I change the existing html website and tutorial to rst and sphinx and once that is in place we discuss what documentation is most needed.

Ok

I think having narrative documentation that explains the most important concepts and classes of the API is much more important and a much smaller task than improving and extending the 80,000 lines of existing, already very good compared to most other projects, docstrings.

Sound great.

Here’s a first version of the sphinx-based docs: https://github.com/cdeil/gammalib/compare/docs

I’ve renamed the doc folder to docs while I was working on the new docs ... we can change this back of course.
Let me know if you want to merge this and improve it incrementally or if you want me to change things in this branch.

Note that there is a very nice tool to convert back and forth between html, rst, latex and other formats:
http://johnmacfarlane.net/pandoc/

pandoc something.html -o something.rst

does 90% of the work and then you just have to clean up a bit.

My suggestion would be that we convert the existing latex documentation in the dev and um folders to rst and include them in the sphinx documentation and then once it’s all rst review and restructure the documentation.
There’s also quite a bit of documentation on the wiki, some of which should probably be merged and cross-linked with these docs.

One more thing: can you make a smaller logo version and banner ... similar to the one where we took the page layout from : http://sphinx-doc.org ?

Christoph Deil wrote:

Here’s a first version of the sphinx-based docs: https://github.com/cdeil/gammalib/compare/docs

Looks good!

I’ve renamed the doc folder to docs while I was working on the new docs ... we can change this back of course.
Let me know if you want to merge this and improve it incrementally or if you want me to change things in this branch.

I prefer doc, which is more the standard name (although there is no standard for directory names ; but when I started I made a search of recommendations for directory structures, and doc is the name that is implemented by most packets).

Note that there is a very nice tool to convert back and forth between html, rst, latex and other formats:
http://johnmacfarlane.net/pandoc/

pandoc something.html -o something.rst

does 90% of the work and then you just have to clean up a bit.

Great. I was using LaTeX in a first for easy formula typing. Can Sphinx also display formulae in a LaTeX style?

My suggestion would be that we convert the existing latex documentation in the dev and um folders to rst and include them in the sphinx documentation and then once it’s all rst review and restructure the documentation.

Good idea, this hopefully helps to get a more living documentation. Needs of course LaTeX embedded as some documents contain quite a bunch of formulae ...

There’s also quite a bit of documentation on the wiki, some of which should probably be merged and cross-linked with these docs.

Right, I tend to use the Wiki for the moment as it is more responsive. It’s also there for elaborating new concepts, as it can be easily modified. But the idea was indeed to merge the stable Wiki information into the documentation. That’s probably better than cross-linking, but we could cross-link to start with ...

One more thing: can you make a smaller logo version and banner ... similar to the one where we took the page layout from : http://sphinx-doc.org ?

I’ll work on one. Are there some constraints on the size of the banner? Will there also be buttons embedded as on http://sphinx-doc.org ?

One thing: I guess you need sphinx installed to generate the documentation, right? Do you know if sphinx is a standard package on each Linux distribution?

There is the same problem with Doxygen, but I think that most distros actually have Doxygen.

In any case, the configure script should detected whether sphinx is available or not, and then enable/disable sphinx document generation accordingly (this is done for doxygen). Then we should have:

make doxygen  <= Builds Doxygen documentation
make sphinx   <= Build sphinx documentation
make doc      <= Calls make doxygen and make sphinx

The Doxygen documentation should be embedded in the sphinx documentation. Do you know whether this is possible?

• Sphinx can have math just like LaTeX: http://sphinx-doc.org/ext/math.html
  If HTML is generated it can do mathjax (new kid on the block, looks better and less files to generate) or pngmath.
  For PDF it actually generates LaTeX sources and then uses latex.
  Try make latexpdf

• Sphinx is available in all repositories as far as I know. For someone that doesn’t have root access pip install works.
  90+ % of the time I use the documentation on the web though, so if someone really has problems installing sphinx or doxygen it wouldn’t be the end of the world.

• We can copy over the buttons from sphinx-docs if you like them ... but we don’t have to.

• For the banner size I would suggest you do something similar as the one on sphinx-docs.org.
  But the layout is completely customisable ... we can make the page look however you like.
  While you’re at it, can you also make a 32 x 32 pix favicon for gammalib?
  Here’s where you set it in the sphinx conf.py file then:
  

  # The name of an image file (within the static path) to use as favicon of the
  # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
  # pixels large.
  #html_favicon = None
  

• The way you propose the build to work is very nice. I did write up something slightly different in docs/README.txt, which we should remove or change.

• I don’t think the doxygen and sphinx docs can interact a lot. I would simply make the doxygen output a sub-folder in the build/html output folder and then add a hard-coded link back and forth in Doxygen and Sphinx. I haven’t tried this yet.

I can work on this some more tomorrow ... can you make sub-tasks and let me know what I should do (e.g. sphinx docs for ctools or convert the latex or some wiki content to rst or ...).

I created feature #841 in the ctools project for the same work.

I’ve worked on this some more: https://github.com/cdeil/gammalib/compare/docs2

• Favicon and banner are now there ... I’m not very versed in html and css, maybe you know how to make the banner fit perfectly?
• Converted user manual and coding conventions to RST.

Things left to do:

• Set up the make sphinx docs as you suggested
• Try to cross-link between the sphinx and doxygen documentation (maybe using absolute links?)
• Convert the other latex documents to RST
• Convert eps figures to png for the html pages
• Include the examples in the sphinx docs
• Move some wiki pages to the docs
• Review and restructure the whole docs: * what should go onto the top-level page? * what kind of links should be in the header? * e.g. installation instructions are present several times. * there's a lot of info e.g. on some details like GVector, but some of the big picture documentation is missing.

Jürgen, I don’t have much time left to work on this before the HESS collaboration meeting next week.
Do you think this could be merged and then the other tasks we will do in the coming months before the 0.8 release?
Can you make a list of things I should still do as part of this PR?

A note on the html and latex conversion to rst: I did

pandoc documentation.html -o documentation.rst
pandoc documentation.latex -o documentation.rst

\newcommand{\task}{\mbox{GammaLib}}
\newcommand{\this}{\mbox{\tt \task}}

Thanks for the nice work.

I added the

make sphinx
make doc

make install

I also renamed the build directory to html, as once it’s build, it is just the html documentation of the project (if we’d install build, nobody would known what has been built

I adapted the Readme.txt file to reflect the changes.

Everything merged into devel, so that we can now work incrementally on the documentation.

Note that with sphinx you can say make latexpdf and that will create by default a latex folder in the build folder.
You might have to adapt the paths in conf.py to make PDF (or man pages) generation work.

For new users / developers there should be tutorials to get started with gammalib as well as a narrative introduction that explains the major concepts and classes.

Currently there are quite nice examples (but not part of a tutorial, with narrative) and there are some PDFs explaining some of the basic gammalib concepts, but this is currently unfinished and a bit hard to find, i.e. not available as html.

I have started to write a “Getting started with gammalib” which we had planned to be part of a tutorial on HESS / Fermi data analysis with gammalib / ctools (see attached tarball).

But really 90% of the tutorial would not use HESS-private info and I think it would be more useful if it were either part of the gammalib repo itself
or a separate gammalib-tutorials repo (because it will contain a lot of images).

I find writing RST and sphinx for generating html and PDF very nice for tutorials / narrative docs, certainly better than the hand-written HTML that is used at the moment for the gammalib and ctools web pages / tutorials.

Jürgen, what do you think?
My suggestion would be we try this out for a few days in a gammalib-tutorials repo on github and if you don’t like it we’ll remove it?

Christoph Deil wrote:

Note that with sphinx you can say make latexpdf and that will create by default a latex folder in the build folder.
You might have to adapt the paths in conf.py to make PDF (or man pages) generation work.

Great, we should explore this ...