fenics team mailing list archive

[Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx>]

On 27 August 2010 18:55, Anders Logg <logg@xxxxxxxxx> 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
>
> ?

OK, let's give it a go.

But in case it fails (I do hope it doesn't) I vote for writing *.rst
files manually and test if the documentation is missing/obsolete (this
is already in place) and testing if the one-line docstrings in *.h
files is present in the *.rst files (could be ready in a day).

The last resort, in my book, would be a link to Doxygen pages.

Kristian

> --
> Anders
>