[Dune-devel] dune-python and auto-generated CMake docs

[Dominic Kempf]

Dear Dune,

I have two projects of mine that I would like to share with you w.r.t. to
the upcoming user/developer meeting:

1) dune-python
I work on a growing number of projects, that do provide python code within
a dune module. I think many others are in the same situation. In that
context, the question arises on how to bring together the dune buildsystem
and the python way of handling distribution and installation. I have worked
on a buildsystem extension, that answers those question:

http://conan2.iwr.uni-heidelberg.de/git/quality/dune-python

The summary of features is:
* Setup a virtualenv at configure time in the build directory
* Integrate the pip installation process into make install
* utilities helpful with python issues, such as searching for installed
packages etc.

To document this build system extension, I have experimented with Sphinx
for generating CMake documentation. The result is:

http://conan2.iwr.uni-heidelberg.de/cmake-documentation/html/index.html

2) Autogenerated CMake documentation with Sphinx
I have written a Sphinx extension to generate above documentation. It is
currently a feature of dune-python, but it could be integrated into
dune-common with a reasonable amount of work. The only thing we would have
to do is rewrite our in-module documentation in reStructured with the
special directives provided in the extension. This does of course lead to
less readable incode doc. See this example of a module:

Source:
http://conan2.iwr.uni-heidelberg.de/git/quality/dune-python/blob/master/cmake/modules/CreateVirtualEnv.cmake

Output:
Command doc:
http://conan2.iwr.uni-heidelberg.de/cmake-documentation/html/commands/create_virtualenv.html
Module doc:
http://conan2.iwr.uni-heidelberg.de/cmake-documentation/html/modules/CreateVirtualEnv.html

If somebody is willing to spend more time on this, there are lots of
additional features possible with this approach, Sphinx is a mighty tool.

Best,
Dominic
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.dune-project.org/pipermail/dune-devel/attachments/20150804/0933b49d/attachment.htm>