Subject: [Fenics] Documentation (summary)

From: Anders Logg <[email-masked]>
Date: Tue, 23 Mar 2010 20:59:31 +0100

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

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

---

From: Kristian Oelgaard <[email-masked]>
Date: Fri, 26 Mar 2010 14:19:31 +0100 (CET)

>  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

> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
>
> iEYEARECAAYFAkupHaMACgkQTuwUCDsYZdFuUQCfazEt4bmEwYwOPOjm4QvCAuYC
> 6isAmgOjHT9ZOHN2goU5dfKHdBve3dCp
> =uoy5
> -----END PGP SIGNATURE-----
>
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : [email-masked]
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp
>
>

---

From: Andy Ray Terrel <[email-masked]>
Date: Fri, 26 Mar 2010 10:55:16 -0500

> As far as I can tell, Sphinx can't process doc strings from C++, but there
> might be some workarounds using Doxygen

Check out this extension:
http://old.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html

Numpy just writes everything out so you can separate the docs from the
code, but if you do that you have to be quite diligent to update the
docs everytime the code changes.

---

From: Andy Ray Terrel <[email-masked]>
Date: Fri, 26 Mar 2010 10:58:47 -0500

2010/3/26 aterrel <[email-masked]>:
> Check out this extension: http://old.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html
>

Oops wrong link: http://github.com/michaeljones/breathe

> Numpy just writes everything out so you can separate the docs from the code, but if you do that you have to be quite diligent to update the docs everytime the code changes.
>

---

From: Anders Logg <[email-masked]>
Date: Fri, 26 Mar 2010 18:10:45 +0100

On Fri, Mar 26, 2010 at 02:19:31PM +0100, Kristian Oelgaard wrote:
> 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.

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).

> 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.

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

---

From: Kristian Oelgaard <[email-masked]>
Date: Mon, 29 Mar 2010 12:19:22 +0200 (CET)

>  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.

> source (using a preprocessor as suggested by Hans Petter).

I also prefer Hake's suggestion.

> 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

> iEYEARECAAYFAkus6pUACgkQTuwUCDsYZdF9AwCfcieXOe/jxmp85Kdjefm4sBDm
> jX0AnizSTPad0NW1ApSr6pNz7ZhWshDp
> =a7+L

---

From: Anders Logg <[email-masked]>
Date: Mon, 29 Mar 2010 12:55:02 +0200

On Mon, Mar 29, 2010 at 12:19:22PM +0200, Kristian Oelgaard wrote:
> 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.

> 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

---

From: Kristian Oelgaard <[email-masked]>
Date: Mon, 29 Mar 2010 13:28:24 +0200 (CET)

> 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

> iEYEARECAAYFAkuwhwYACgkQTuwUCDsYZdGWjQCgkFKOJlIsJimnd+2dbgsphvH5
> S+4Anjx+VFRlAQ6mkR0VwPTqwvWQJ/8b
> =BQaF

---

From: Johan Hake <[email-masked]>
Date: Mon, 29 Mar 2010 21:44:42 -0700

On Monday March 29 2010 04:28:24 Kristian Oelgaard wrote:
> 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. 

Agree, or maybe docstrings.py?

> 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?

Maybe use docstrings for now, and if it get out of proportion, which I do not 
think it will, we can consider putting it in its own documentation files. 

Johan