On Fri, Aug 27, 2010 at 01:09:06PM +0200, Kristian Ølgaard wrote: > On 27 August 2010 12:12, Kristian Ølgaard <[email protected]> wrote: > > On 27 August 2010 12:00, Garth N. Wells <[email protected]> wrote: > >> > >> > >> On 27/08/10 10:51, Kristian Ølgaard wrote: > >>> On 27 August 2010 11:31, Garth N. Wells <[email protected]> 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 : [email protected] > >>>>>>>>> Unsubscribe : https://launchpad.net/~fenics > >>>>>>>>> More help : https://help.launchpad.net/ListHelp > >>>>>>>> > >>>>>> > >>>> > >>>> > >> > > -- Anders _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
