On 13 September 2010 11:51, Anders Logg<logg@xxxxxxxxx> wrote:
On Mon, Sep 13, 2010 at 11:38:41AM +0200, Kristian Ølgaard wrote:
The FEniCS documentation is almost complete. Below is a short list of
what remains to be done and a sketch of how we will handle the
programmer's reference part the design of which has been debated
intensely over the past weeks.
* Tutorial
- Hans Petter is working on translating his TEX source to reST for
the Python version.
- Figure out if there are some common parts of the text which can be
shared with the C++ version.
- Fill in blanks for C++ version.
- This work can be completed independently of the other parts since
we can already use references like
:py:class:`Foo` :cpp:class:`Foo`.
* Demos
- Framework is in place.
- Add documentation for all demos in the dolfin/demo/undocumented directory.
- Again, this work can be completed independently of the other parts
since we can already use references like
:py:class:`Foo` :cpp:class:`Foo`.
* Style guides
- Once the programmer's reference is complete we need to update this
section in the style guides accordingly.
* Programmer's reference
- Add module to extract docstrings from *.h files to DOLFIN.
Anders' script is already working but we need to define the
intermediate representation (IR).
- Make write_cpp_documentation() work with the intermediate representation.
The C++ version of programmer's reference is more or less complete.
- From the IR generate the docstrings.i file in DOLFIN.
We need to handle the example code (C++ --> Python syntax) and the
native arguments like double* --> numpy.array.
- Add complete docstrings to the extended methods in *_post.i files
and the Python layer in dolfin/site-packages/dolfin,
the idea being that documentation should be located where the code is.
- In fenics-doc we will import the dolfin module and use it to
generate the reST files and autodoc from Sphinx to handle the
docstrings.
To get a meaningful module structure we have to be more careful
when including classes/functions in the __init__.py file in dolfin.
Classes from dolfin.cpp which are not imported in other modules
(like dolfin.mesh, dolfin.la etc.) will not be included in the
documentation.
The above should increase the chances of the source code in DOLFIN and
the documentation being in sync as well as reduce the work involved
writing documentation for both interfaces. We will also have the same
documentation available in>>> help(dolfin) as we have in the online
documentation.
Finally, the appendices for FFC, UFC and UFL needs to be written. I
think we can handle FFC and UFL by improving the docstrings in the
modules (this will also help developers while writing the code) and
use autodoc from Sphinx, maybe with some autogenerated reST files.
The documentation for UFC might have to be written manually, but since
the idea is that the interface should not change too rapidly I think
this is an OK solution.
There's your summary Anders, now let's hear your completely different
approach to documenting the FEniCS project :)
I actually think this looks good! :-) Just a couple of questions/comments:
1. I don't understand how the docstrings in *_post.i files is supposed
to work. How does one write them and how are they extracted?
For example in the function_post.i we extend the
Function.function_space() function. The docstring for this function
could be more detailed, and if we want this we should improve it in
the function_post.i file so we don't have to worry about it later.
This is what I mean when I wrote that documentation for Python goes
where the code is.
2. For FFC, UFC and UFL, we have pretty good manuals already, so would
it be possible to just use that as a starting point, convert to reST
with some extra manual editing? Or should it all be part of the code?
Sure, we can write all the introduction and basic design and ideas by
hand by translating what we have.
Note that stuff like the language chapters etc. in FFC can be omitted
since this is part of UFL now.
But we might also want to document the interface for FFC/UFL which we
can generate automatically.
3. Perhaps it would be a good idea to divide the documentation effort
between all developers, like having a system where everyone signs up
to document a specific demo.
Yes, definitely. The style guide is relatively detailed and the demos
which are already there serve as good references.
I also created a template for demos (containing foo/common.txt,
foo/cpp/documentation.rst and foo/python/documentation.rst) which can
be downloaded from the demos style guide page.
