fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

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.

Perhaps it should say

 (join team before posting)

on each line after the mailing lists?

> >>>> * 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 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