fenics team mailing list archive

[Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx>]

On 13 September 2010 14:54, Garth N. Wells <gnw20@xxxxxxxxx> wrote:
>
>
> On 13/09/10 11:08, Kristian Ølgaard wrote:
>>
>> 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.
>>
>
> I agree think that it's good to use we have has a start. FFC probably only
> needs a very minimal user doc (installation + command line flags).
>
>
>>> 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.
>>
>
> Sounds good. We could have just one blueprint and claim demos on the
> blueprint whiteboard.

I've added the list to:

https://blueprints.launchpad.net/fenics-doc/+spec/demos

Kristian

> Garth
>
>>> 4. I made a bunch of notes when we worked with the docs a couple of
>>> weeks back. I have them on a piece of paper at the office. Some of
>>> these you have already fixed but I'll check what else I thought of.
>>
>> OK, sounds good.
>>
>> Kristian
>>
>>> --
>>> Anders
>>>
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~fenics
>> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~fenics
>> More help   : https://help.launchpad.net/ListHelp
>
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp
>