On 27 August 2010 18:55, Anders Logg <[email protected]> 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 > > ?
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 > _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
