fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

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.
> >
>
> 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.

Perhaps we'll find that we should use a fancy tool like Doxygen, but
it seems it's not that complicated and it took a very short time to
write our own script.

--
Anders