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.
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. Kristian
This is very much a question of taste and it may sometimes be difficult to find a rationale for all opinions (my own included) so discussions are welcome. -- AndersKristian >Any comments or suggestions are welcome. Things are still up for >discussion but I hope Kristian can get started soon on building the >documentation. > >Even though Kristian will have the main responsibility for >coordinating and writing most of the documentation, I hope we can all >help out to create some really good documentation. For example, >Kristian could assign tasks for people to document certain functions, >or ask for help with proofreading. >-----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) iEYEARECAAYFAkus6pUACgkQTuwUCDsYZdF9AwCfcieXOe/jxmp85Kdjefm4sBDm jX0AnizSTPad0NW1ApSr6pNz7ZhWshDp =a7+L -----END PGP SIGNATURE-----
signature.asc
Description: OpenPGP digital signature
_______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
