fenics team mailing list archive
-
fenics team
-
Mailing list archive
-
Message #00801
Re: Documentation (summary)
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.
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.
--
Anders
Kristian
>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-----
Attachment:
signature.asc
Description: OpenPGP digital signature
Follow ups
References
