fenics team mailing list archive

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

On 25 October 2010 09:49, Anders Logg <logg@xxxxxxxxx> wrote:
> On Thu, Oct 21, 2010 at 03:06:49PM +0200, Kristian Ølgaard wrote:
>> 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.
>> >>>>>
>> >>>>
>> >>>> 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.
>
> Great.
>
>> >>>> * 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.
>
> Looks good. There are some inconsistencies wrt use of ':' or not.

Fixed.

> Perhaps it should say
>
>  (join team before posting)
>
> on each line after the mailing lists?

Good idea, I added this.

>> >>>> * 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.
>
> Looks good. I wonder if one should move the picture up a bit so it
> comes at the end of the first paragraph, just before 1.1, so one sees
> the picture directly without scrolling. That gives a more pleasant
> first impression I think.

I played around with the position of pictures, but apparently the
':align: center' option makes the text flow around it in a not so nice
way when the image is placed at the top. I'm not sure how we can fix
this, but perhaps we can use our own css file to force the position
and layout using the :class: option although I'm not familiar with
this feature of Sphinx/reStructuredText.
Using no alignment looks better, compare the Poisson demo (no
alignment), to the biharmonic  where ':align: center' has been used
and the Cahn-Hilliard demo which uses the original layout with a
picture of the solution after the input values and ':align: center'.

Kristian


>> >>> 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.
>
> ok!
>
> --
> Anders
>