fenics team mailing list archive

[Kristian Oelgaard <k.b.oelgaard@xxxxxxxxx>]

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?

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.

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.
>
> --
> Anders
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
>
> iEYEARECAAYFAkupHaMACgkQTuwUCDsYZdFuUQCfazEt4bmEwYwOPOjm4QvCAuYC
> 6isAmgOjHT9ZOHN2goU5dfKHdBve3dCp
> =uoy5
> -----END PGP SIGNATURE-----
>
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp

Attachment: signature.asc
Description: OpenPGP digital signature