fenics team mailing list archive

[Johan Hake <johan.hake@xxxxxxxxx>]

On Friday August 27 2010 09:55:41 Anders Logg wrote:
> On Fri, Aug 27, 2010 at 01:30:56PM +0200, Kristian Ølgaard wrote:
> > On 27 August 2010 13:17, Anders Logg <logg@xxxxxxxxx> wrote:
> > > On Fri, Aug 27, 2010 at 12:11:10PM +0100, Garth N. Wells wrote:
> > >> On 27/08/10 12:09, Anders Logg wrote:
> > >> > On Fri, Aug 27, 2010 at 12:12:59PM +0200, Kristian Ølgaard wrote:
> > >> >> On 27 August 2010 12:00, Garth N. Wells <gnw20@xxxxxxxxx> wrote:
> > >> >>> On 27/08/10 10:51, Kristian Ølgaard wrote:
> > >> >>>> On 27 August 2010 11:31, Garth N. Wells <gnw20@xxxxxxxxx> wrote:
> > >> >>>>>>>>>> The stuff that you have written for the Mesh class could
> > >> >>>>>>>>>> easily go in to Mesh.h without causing too much clutter
> > >> >>>>>>>>>> (reST looks nice), and I imagine it would be easy to add a
> > >> >>>>>>>>>> folding mode to Emacs and other editors that will hide all
> > >> >>>>>>>>>> lines starting with /// except for the first line.
> > >> >>>>>>>>>> 
> > >> >>>>>>>>>> The simple script I wrote seems to work pretty well to
> > >> >>>>>>>>>> extract the documentation. If it breaks somewhere, we
> > >> >>>>>>>>>> could either improve the script or learn to write the code
> > >> >>>>>>>>>> so the script does not break.
> > >> >>>>>>>>>> 
> > >> >>>>>>>>>> The point here is that now the generated .rst files are in
> > >> >>>>>>>>>> sync with the code, but in a day or two someone will edit
> > >> >>>>>>>>>> one of the .h files in DOLFIN and the documentation and
> > >> >>>>>>>>>> code will start to diverge.
> > >> >>>>>> 
> > >> >>>>>> On second thought, what do you mean by diverge?
> > >> >>>>>> I have test scripts in place the checks if a function in *.h is
> > >> >>>>>> documented in *.rst, and if a function in *.rst is still
> > >> >>>>>> present in *.h.
> > >> >>>>>> 
> > >> >>>>>> If you mean the docstrings might change, we can perform the
> > >> >>>>>> additional check where we test if the one liner docstring in
> > >> >>>>>> *.h is present in the documentation in *.rst, then there can
> > >> >>>>>> be no divergence and we can have short comments in the DOLFIN
> > >> >>>>>> source code.
> > >> >>>>>> 
> > >> >>>>>>>> Yes, but this problem is already there for the Python
> > >> >>>>>>>> interface and it won't go away.
> > >> >>>>>>>> I guess the key thing to this is that a new feature or a
> > >> >>>>>>>> change in DOLFIN source code is not complete until the
> > >> >>>>>>>> documentation has been updated.
> > >> >>>>>>> 
> > >> >>>>>>> To save ourselves work for now, we could just let doxygen
> > >> >>>>>>> create the C++ programmers reference and provide a link to
> > >> >>>>>>> it. It doesn't seem very sensible that we write our own
> > >> >>>>>>> parser to document the C++ code. With doxygen, we also get
> > >> >>>>>>> class diagrams. We can then scan the doxygen documentation
> > >> >>>>>>> for each class and improve it iteratively.
> > >> >>>>>> 
> > >> >>>>>> Do you mean improve the Doxygen output, or the source  code
> > >> >>>>>> (*.h files)? If we improve the output we can get diverging
> > >> >>>>>> docs and code.
> > >> >>>>> 
> > >> >>>>> I mean improve the strings following '///' in the .h files. In
> > >> >>>>> quite some cases, just a few extra words would make a big
> > >> >>>>> difference.
> > >> >>>>> 
> > >> >>>>> I'm coming around to putting all programming reference doc in
> > >> >>>>> the code. I don't like lots of markup, but I don't see any
> > >> >>>>> other robust and easily maintainable solution.
> > >> >>>> 
> > >> >>>> As I wrote above, a test script is in place to pick up
> > >> >>>> missing/obsolete docs, very little extra work is needed to also
> > >> >>>> test if the short docstring in the source  code is correct. Then
> > >> >>>> we run the tests as part of building the documentation.
> > >> >>> 
> > >> >>> I just can't see myself hopping back and forth between the code
> > >> >>> and the documentation when implementing and testing something
> > >> >>> new.
> > >> >> 
> > >> >> I don't see why that would be necessary, the documentation can be
> > >> >> updated and built later once the feature is in place and tested.
> > >> >> But the feature can't be 'official' until it has been documented,
> > >> >> it will require more self-discipline from the developers, which I
> > >> >> don't think is necessarily a bad idea.
> > >> >> 
> > >> >>>> I admit that the Doxygen output is much more detailed and the
> > >> >>>> type information/links in argument lists is better compared to
> > >> >>>> what is in Sphinx now, but that might change in the future (in
> > >> >>>> Sphinx). On the downside, I personally find the Doxygen
> > >> >>>> documentation overwhelming and I never use it for just that
> > >> >>>> reason.
> > >> >>> 
> > >> >>> Doxygen is an (imperfect) ready made solution for the programmers
> > >> >>> reference - so one of my points is that we can forget about the
> > >> >>> C++ programmers reference for now and get on with the more
> > >> >>> importance task of documenting demos. We can return to the C++
> > >> >>> programmers reference later (which, as you say, may improve in
> > >> >>> Sphinx in the future).
> > >> >> 
> > >> >> I'm fine with using Doxygen and simply put a link to the index
> > >> >> page, I just think it is worthwhile to carefully discuss the pros
> > >> >> and cons.
> > >> >> 
> > >> >> The Python interface still has to be documented manually since
> > >> >> there is no way to extract docstrings from the source code since
> > >> >> the intention is to add docstrings to the module.
> > >> >> 
> > >> >>> We can some some very limited work to improve the doxygen output
> > >> >>> which will make it easier to navigate.
> > >> >> 
> > >> >> I just don't see how this can be integrated easily with the output
> > >> >> from Doxygen. We don't want to manipulate the output files since
> > >> >> they will be re-generated whenever we build the docs. It is
> > >> >> possible though to link to the html pages of classes/functions,
> > >> >> but it won't be naturally supported like it would be if everything
> > >> >> is in Sphinx.
> > >> >> 
> > >> >> Kristian
> > >> > 
> > >> > I think that the simple script we have now does a fairly good job at
> > >> > extracting the documentation. I like having it as part of the
> > >> > reST-based documentation (so it looks like it's part of the
> > >> > documentation), rather than as a separate set of pages generated by
> > >> > Doxygen. But I wouldn't mind having Doxygen-generated pages in
> > >> > addition.
> > 
> > I agree that having it in reST makes it look more like it is a part of
> > the documentation.
> > 
> > >> The doc generated by the script lacks links, which is a big drawback.
> > >> 
> > >> Garth
> > > 
> > > Links to other classes you mean?
> > > 
> > > That would be easy to add to the script. We could just insert labels
> > > and references into the generated code.
> > 
> > What I have done with the links in the Mesh.rst so far is to put it in
> > 
> > the *Arguments* section like:
> > :cpp:class:`Point`, we can have still have this as part of the source
> > 
> > code in the *.h files.
> > 
> > Kristian
> 
> ok. Does everyone agree that as a first iteration, it would be good to
> at least try to:
> 
> 1. Move over the stuff from Mesh.rst (in the doc repo) to Mesh.h (in
> DOLFIN)
> 
> 2. Generate all .rst files in the doc repo from the C++ code
> 
> 3. Evaluate if we can live with the more heavy commenting in the .h
> files (or find a folding mode)
> 
> 4. Evaluate if the simple extract script does its job well enough

Sounds good. I was in favour of a more heavily commented .h files in the first 
place. Then using Doxygen. But I agree that Doxygen isn't the nices markup 
language, and using just one is probably a strength. I also agree with 
Kristian that Doxygen generated references can be too overwhelming...

If we can just deal with the extraction of the comments, which I figure Anders 
script allready does(?), we should be able to handle this in a nice way. 
Slightly over crowded .h files has never been an issue for me. You have the 
progammers reference for looking into class definitions and such ;)

It also leaves the possibilities that Sphinx get better in parsing C++. I see 
that there where some GSOC project description for this year adressing this 
issue, but not sure if it got accepted or how it went.

What does not the script of Anders extract? I think you have mentioned it in 
the other thread but I lost sight...

Johan

> ?
> 
> --
> Anders
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp