| Thread Previous • Date Previous • Date Next • Thread Next |
On 29 March 2010 12:55, Anders Logg <logg@xxxxxxxxx> wrote:
On Mon, Mar 29, 2010 at 12:19:22PM +0200, Kristian Oelgaard wrote:On 26 March 2010 19:10, Anders Logg <logg@xxxxxxxxx> wrote: >On Fri, Mar 26, 2010 at 02:19:31PM +0100, Kristian Oelgaard wrote: >> >> >>On 23 March 2010 20:59, Anders Logg <logg@xxxxxxxxx> 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.
A last (for now) remark on the doc-strings, when generated in a separate folder/project I think the doc-strings for the dolfin module should be dumped in a module say docs.py and copied to the correct location in the DOLFIN source tree manually to avoid a dependency between the two projects. Also, do we want to handle doc-strings for the pure Python projects like FFC, UFL etc. in the same way or should we extract documentation from doc-strings as these modules have a much more shallow tree structure which makes the documentation more manageable, or should we strive to keep things uniform across the projects? Kristian
>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 -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) iEYEARECAAYFAkuwhwYACgkQTuwUCDsYZdGWjQCgkFKOJlIsJimnd+2dbgsphvH5 S+4Anjx+VFRlAQ6mkR0VwPTqwvWQJ/8b =BQaF -----END PGP SIGNATURE-----
Attachment:
signature.asc
Description: OpenPGP digital signature
| Thread Previous • Date Previous • Date Next • Thread Next |
