On Mon, Mar 29, 2010 at 12:19:22PM +0200, Kristian Oelgaard wrote: > > > On 26 March 2010 19:10, Anders Logg <[email protected]> wrote: > >On Fri, Mar 26, 2010 at 02:19:31PM +0100, Kristian Oelgaard wrote: > >> > >> > >>On 23 March 2010 20:59, Anders Logg <[email protected]> wrote: > >>>It looks like we have converged towards reST/Sphinx to be used for > >>>both the C++ and Python interfaces, as well as for docstrings. > >>> > >>>I have summarized some of my conclusions here: > >>> > >>> https://blueprints.launchpad.net/fenics-doc > >> > >>Looks good, the only thing I don't agree with (possibly because I > >>don't understand it) is why we will use reST and Sphinx to generate > >>the doc strings for the Python modules. As I see it, Sphinx focuses > >>on handwritten documentation with the ability to auto-generate > >>documentation from doc-strings if needed. So I don't see a use for > >>generating a doc-string in Sphinx and then add it to some function, > >>what good will that do anyway to a developer who has opened a *.py > >>file to modify it? > > > >The motivation is the following: > > > >1. We want to split out the documentation so that it is not part of > >the code. The reasons for this are: > > > > 1.a) It may otherwise be hidden deep inside the code and difficult > > to edit, the prime example being the documentation of Expressions in > > Python, which is now hidden deep inside a very complex piece of > > code that handles the metaclass magic for Expressions. > > > > 1.b) It may otherwise clutter the code (especially for the otherwise > > clean C++ header files) and result in something like 90% > > documentation and 10% code. Then it's not code with documentation, > > it's documentation with some function declarations here and there. > > > > 1.c) It's easier to edit, spell-check, grammar check, translate etc > > if it is maintained separately. > > I agree to all this, so instead of the rather extensive doc-strings > we have now, we will just have one-liners (which will be overwritten > when importing the dolfin module) like we have in the C++ part of > DOLFIN to help developers working in the source files.
Yes, something like that. It can either be one-liners or it can be empty. I'm not sure which is best. > >2. The same documentation should appear in the docstrings (when typing > >help(Expression) or help(assemble) in Python) as in the manual (to > >avoid duplication of effort). Since by (1) we don't extract the > >documentation from the code, we must either do the opposite (which I > >prefer), or generate both documentation and docstrings from a third > >source (using a preprocessor as suggested by Hans Petter). > > I also prefer Hake's suggestion. > > >>As far as I can tell, Sphinx can't process doc strings from C++, but > >>there might be some workarounds using Doxygen if we decide that we > >>need it, otherwise we can still use Sphinx and simply write > >>everything by hand. > > > >We could use the Breathe (as pointed out by Andy) but my suggestion > >would be to have hand-written documentation (and then some script to > >check for missing documentation). Perhaps there's a way to use Doxygen > >to extract the function signatures and the one-line compact comment, > >then fill in the rest by hand. > > Sounds like a lot of work to get just one line of documentation, if > we can just run a script to check for functions/classes with missing > documentation, that will be enough. Agree. -- Anders
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
