fenics team mailing list archive

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

On 21 October 2010 12:28, Anders Logg <logg@xxxxxxxxx> wrote:
> Kristian Ølgaard skrev 2010-10-21 11.47:
>>
>> 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.
>
> I don't have any strong opinion. I think we decided to go with lowercase for
> the FEniCS book chapters. Possibly it was Marie that suggested to do
> lowercase.

I changed it to lowercase.

>>>> * The Launchpad pages page is still missing
>>>
>>> The page is there, but the links are missing.

Fixed, I put all the links to projects listed on
https://launchpad.net/fenics-project and included FEniCS Apps.
Feel free to add more links in case I missed any.

>>>> * 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?
>
> Sounds good.

I added a picture to the Poisson demo, check it out and see how it
looks. If we're happy I can add the rest and include some appropriate
info in the style guide.

>>> 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.
>
> Sounds good. Make sure to save some time for writing up a summary of the
> status, any loose ends that need fixing etc.

Of course, it'll just be a slightly modified version of the list
presented in this thread.

Kristian

> --
> Anders
>