fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Fri, Aug 27, 2010 at 01:09:06PM +0200, Kristian Ølgaard wrote:
> On 27 August 2010 12:12, Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx> 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.
>
> Let's wait for someone else (Anders?) to comment on this before making
> a decision.

I think we can have both side by side (since both are working), but I
prefer having the reST comments as part of the code and using our own
script to extract it (or in the future built-in support in Sphinx if
that should come). If we use Doxygen, we will need to use some special
Doxygen-markup.

> On a related note, it is interesting that only the three of us appears
> to have an opinion about the look and feel of the documentation of the
> programmer's reference. Are we perhaps making a big deal out of
> something which nobody will use anyway?

I would be good to get some more comments from others.

> > 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.
>
> Since we do need this, I'll start documenting the Python interface
> starting with the functions and classes in the cpp.py module.

I still haven't understood completely how the Python documentation is
organized, but won't we be documenting Python code (the stuff we write
in site-packages/dolfin as part of the code?

--
Anders



> Kristian
>
> >> 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
> >
> >
> >> Garth
> >>
> >>>> Perhaps we should settle on well crafted, handwritten docs for the demos
> >>>> (which is the most important), and all programming reference docs coming
> >>>> automatically from the source code. When scanning auto generated docs,
> >>>> it easy to pick up quickly where more detail needs to be added, and we
> >>>> can open open up the source and add it.
> >>>
> >>> A benefit of having the manually written programmer's reference is
> >>> that it is easy to link to demos for additional information (and the
> >>> other way around).
> >>>
> >>> If we use automatically generated docs, we can only link to the
> >>> programmer's reference when documenting demos (it won't be well
> >>> integrated in Sphinx though and it might break more easily).
> >>>
> >>> I agree that well documented demos is most important since this is
> >>> what users will be copying anyway.
> >>>
> >>> Kristian
> >>>
> >>>> Garth
> >>>>
> >>>>> I had a look at the Breathe generated docs from Doxygen, it doesn't
> >>>>> look that great and we won't have all the links from the index page to
> >>>>> the classes.
> >>>>>
> >>>>> Kristian
> >>>>>
> >>>>>> Garth
> >>>>>>
> >>>>>>> Kristian
> >>>>>>>
> >>>>>>>>>
> >>>>>>>>> _______________________________________________
> >>>>>>>>> Mailing list: https://launchpad.net/~fenics
> >>>>>>>>> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> >>>>>>>>> Unsubscribe : https://launchpad.net/~fenics
> >>>>>>>>> More help   : https://help.launchpad.net/ListHelp
> >>>>>>>>
> >>>>>>
> >>>>
> >>>>
> >>
> >

--
Anders