GammaLib

Here’s a working prototype how to link from Sphinx to Doxygen using https://pypi.python.org/pypi/sphinxcontrib-doxylink :
https://github.com/cdeil/gammalib/compare/issue_1068
It’s just for illustration and uses hardcoded PATHs, don’t merge it.

Jürgen, can you implement this properly into the GammaLib autotools build?
Here’s an example how to do it:
https://github.com/chrisvana/shark_copy/blob/master/doc/sphinx_pages/conf.py.in#L19

I haven’t looked at how to link from Doxygen to Sphinx, I suggest we don’t implement this for now and wait if the need comes up.

Once this is integrated into the GammaLib build system there’s two more things to do:

• Figure out why these errors occur when `doxylink` parses the tag file:
  https://gist.github.com/cdeil/8416583
• Go through the RST docs and add :doxy: directives for all the GammaLib classes / functions.

I could quickly do this, so please re-assign to me if you want me to.

• change conf.py to conf.py.in to make the script configurable
• check whether the special Sphinx python package exists on the system (in configure.ac)
• modify conf.py.in to add automake options / directives
• add generation of this file to configure.ac

Turns out no changes to the build system are needed.

Could you please review this:
https://github.com/cdeil/gammalib/compare/issue_1068

I plan to continue working on the docs in the next few days, but maybe it would make sense to merge this now and continue in a new branch?

There’s two remaining small issues ... I’ve emailed the sphinxcontrib-doxylink author yesterday ... simplest to just paste the email here than to re-describe the issue:

On 08 Jul 2014, at 14:16, Christoph Deil <deil.christoph@gmail.com> wrote:

Dear Matt,

thanks for creating sphinxcontrib-doxylink!!!

I am currently adding it to GammaLib [1] and I’m getting a few parser errors [2].
The tag file is here: [3].

Please let me know if you need any other info or if the error is in our code or Doxygen file.

Cheers, Christoph

[1] http://gammalib.sourceforge.net/
[2] https://gist.github.com/cdeil/70fcaa3c0127305bac5a
[3] https://gist.githubusercontent.com/cdeil/3da996b6848f4c825dfc/raw/GammaLib.tag

Hello again,

another issue I noticed is that linking to some methods doesn’t work (whereas most methods work fine).

E.g. I wanted to link via :doxy:`GObservation::model` to this method:
http://gammalib.sourceforge.net/doxygen/classGObservation.html#a80484fbd8d218c0dc5264e600851de09

but I get this error:
/Users/deil/code/gammalib/doc/source/user_manual/modules/model.rst:27: WARNING: Could not find match for `GObservation::model` in `doc/html/doxygen/GammaLib.tag` tag file

I think this is the relevant entry in the GammaLib.tag file so it should work?

<member kind="function" virtualness="virtual">
      <type>virtual double</type>
      <name>model</name>
      <anchorfile>classGObservation.html</anchorfile>
      <anchor>a80484fbd8d218c0dc5264e600851de09</anchor>
      <arglist>(const GModels &models, const GEvent &event, GVector *gradient=NULL) const </arglist>
    </member>

Cheers,
Christoph

At the moment the online docs have broken links that look like

:doxy:`GOptimizerFunction`

See e.g. here:
http://gammalib.sourceforge.net/user_manual/modules/opt.html

This needs installation of https://pypi.python.org/pypi/sphinxcontrib-doxylink on the server that is used to build the documentation. Seems not trivial for the moment, but can certainly be solved.