fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Fri, Aug 27, 2010 at 02:10:24PM -0700, Johan Hake wrote:
> 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...

The script reads all .h files and finds:

  /// Comments

followed by either a class declaration or a function declaration. Then
just generates .rst for that.

--
Anders