On Mon, Mar 22, 2010 at 03:08:32PM +0100, Kristian Oelgaard wrote: > > > On 22 March 2010 14:50, Anders Logg <[email protected]> wrote: > >On Thu, Mar 18, 2010 at 09:22:24AM -0500, Andy Ray Terrel wrote: > >>I've never heard of doconce. Is there a link somewhere? Just to > >>throw this out there you might check out the way Numpy and Scipy does > >>theirs (I believe with sphinx [0] which has that nice feature of > >>publishing to pdf or html). If there was some style guide set up and > >>the key areas pointed out, it might be good to have a documentation > >>marathon for FEniCS'10. > >> > >>[0] http://sphinx.pocoo.org/ > > > >I looked a bit more on Sphinx, and it looks really good. > > > >The documentation for Sphinx states the following: > > > > The focus is on hand-written documentation, rather than > > auto-generated API docs. > > So we will abandon Doxygen and similar tools? Sounds good to me, but > I guess it will make it slightly more difficult to ensure that all > functions are documented and not forgotten. But maybe there are > tools for this?
I imagine we can write a script that checks for functions that need to be documented. We could also have a script that checks that the one-line compact comment in the code is the same as the summary/first sentence in the hand-written documentation. > >This seems to fit very well with our discussion regarding whether or > >not to put the documentation as part of the code. > > So we only put short comments in the code like we do now, and then > put documentation in sphinx source files. That would be my suggestion. Let's hear what people think. -- Anders > >So Sphinx would be a tool we could use to produce good looking, > >cross-referenced, indexed documentation from a set of simple input > >files (in reST or doconce format), but we would not extract anything > >from the code. > > > >With this approach, I wonder where the limitations are for documenting > >the C++ interface. Are there any? If we don't use Doxygen, we would > >just write the documentation in the same way as for the Python > >interface. > > > >And I just thought of another reason for splitting the documentation > >from the code which is that it makes it possible to separate write > >access for the code and the documentation. > > Good point. > > Kristian > >
signature.asc
Description: Digital signature
_______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
