fenics team mailing list archive

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

On 21 October 2010 11:35, Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx> wrote:
> On 21 October 2010 11:01, Anders Logg <logg@xxxxxxxxx> wrote:
>> Anders Logg skrev 2010-09-13 11.51:
>>>
>>> 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?
>>>
>>> 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?
>>>
>>> 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.
>>>
>>> 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.
>>>
>>> --
>>> Anders
>>
>> Hi Kristian,
>>
>> I found the notes I made. Most issues have already been fixed, but here are
>> some more that need fixing:
>>
>> * Consistent capitalization of headings
>>
>> There seems to be a mix now for different pages. This needs to be looked at,
>> fixed and also be noted in the style guide.
>
> OK.

Do we want:

Getting Help, FEniCS Python Demos, FEniCS Programmer’s Reference etc.

or

Getting help, FEniCS Python demos, FEniCS programmer's reference?

I'm indifferent, and since the distribution between styles is 50-50
the work is the same changing one to the other.

Kristian

>> * The Launchpad pages page is still missing
>
> The page is there, but the links are missing.
>
>> * Pictures on demo pages
>>
>> It would be nice to add a picture to each demo documentation page. The
>> picture can just be whatever comes out of Viper when running the demo.
>> (Store a picture by pressing 'i' in the plot window.)
>
> OK, perhaps we can include it in the common section?
>
>> Do you still have any hours left on your contract? I know the contract has
>> run out but I think you said you had some hours left to work.
>
> I have approx. 30 hours. I think it should be enough time to implement
> the above, fix the handling of arguments for the programmer's
> reference (Python version) and update the style guide to match the new
> approach to generating the programmer's reference. Then all bases
> should be covered and we just need to fill in the blanks.
>
> Kristian
>
>> --
>> Anders
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~fenics
>> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~fenics
>> More help   : https://help.launchpad.net/ListHelp
>>
>