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 <[email protected]> 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 <[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. > > > >> >> > > > >> >> 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 _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
