Subject: [Fenics] FEniCS documentation status

From: Kristian Ølgaard <[email-masked]>
Date: Mon, 13 Sep 2010 11:38:41 +0200

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 :)

Kristian

---

From: Anders Logg <[email-masked]>
Date: Mon, 13 Sep 2010 11:51:19 +0200

> 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

---

From: Kristian Ølgaard <[email-masked]>
Date: Mon, 13 Sep 2010 12:08:51 +0200

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

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

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

> these you have already fixed but I'll check what else I thought of.

OK, sounds good.

Kristian

---

From: "Garth N. Wells" <[email-masked]>
Date: Mon, 13 Sep 2010 13:54:52 +0100

On 13/09/10 11:08, Kristian Ølgaard wrote:
> On 13 September 2010 11:51, Anders Logg<[email-masked]>  wrote:
>>> documentation available in>>>  help(dolfin) as we have in the online
>>> documentation.
>>>

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).

> be downloaded from the demos style guide page.

Sounds good. We could have just one blueprint and claim demos on the 
blueprint whiteboard.

Garth

> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : [email-masked]
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp

---

From: Anders Logg <[email-masked]>
Date: Mon, 13 Sep 2010 15:04:05 +0200

On Mon, Sep 13, 2010 at 01:54:52PM +0100, Garth N. Wells wrote:
> 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).

+ Python interface

> Sounds good. We could have just one blueprint and claim demos on the

I'm sure people will just rush in to claim as many demos as they
can. :-)

Perhaps it would work to do what we did a couple of years back, to set
weekly or bi-weekly deadlines so we all feel a little peer-pressure to
get things done.

--
Anders

---

From: Johan Hake <[email-masked]>
Date: Mon, 13 Sep 2010 08:33:13 -0700

On Monday September 13 2010 02:38:41 Kristian Ølgaard wrote:
>   - 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
> 
>   - Make write_cpp_documentation() work with the intermediate
> representation. The C++ version of programmer's reference is more or less
> complete. 

I guess we are going to include the type and number of arguments of each 
function/method in the IR. It would be usefull to generate a dictionary that 
map these to Python types. Most should be possible to automate, like removal 
of const, pointers and references. But for the types we include our own 
typemaps we probably need to go in and edit the Python type manually.

I am also curious of how you think we are going to handle the C++ -> Python 
code in the example section.

>     the idea being that documentation should be located where the code is.

Sounds good!

> (like dolfin.mesh, dolfin.la etc.) will not be included in the

Sounds good!

Johan

---

From: Kristian Ølgaard <[email-masked]>
Date: Mon, 13 Sep 2010 18:54:47 +0200

> typemaps we probably need to go in and edit the Python type manually.

I think we just need a handwritten map, I don't think there will be that many.
Let's start writing the script and see how much we can automate.

> code in the example section.

We might have to settle for a dictionary as a first implementation
although I have thought about writing a Python <---> C++ converter for
DOLFIN to make it easier to debug demo.py files and wrap main.cpp +
UFL files in a scripting environment.

Kristian

---

From: Johan Hake <[email-masked]>
Date: Mon, 13 Sep 2010 10:00:42 -0700

On Monday September 13 2010 09:54:47 Kristian Ølgaard wrote:
> >> directory. - Again, this work can be completed independently of the
> >> other parts since we can already use references like
> >> 
> >> representation. The C++ version of programmer's reference is more or
> >> less complete.
> > function/method in the IR. It would be usefull to generate a dictionary
> > that map these to Python types. Most should be possible to automate,
> > like removal of const, pointers and references. But for the types we
> > include our own typemaps we probably need to go in and edit the Python
> > type manually.
> 
> I think we just need a handwritten map, I don't think there will be that
> many. Let's start writing the script and see how much we can automate.

Ok.

> > I am also curious of how you think we are going to handle the C++ ->
> > Python code in the example section.
> 

Sounds cool! 

But why do you need to wrap

  main.cpp + UFL files

when you have PyDOLFIN ;)

Johan

---

From: Kristian Ølgaard <[email-masked]>
Date: Tue, 14 Sep 2010 12:58:33 +0200

On 13 September 2010 14:54, Garth N. Wells <[email-masked]> wrote:
>>>> directory.
>>>> representation.
> 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).
>
>

I've added the list to:

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

Kristian

---

From: Anders Logg <[email-masked]>
Date: Thu, 21 Oct 2010 11:01:53 +0200

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

* The Launchpad pages page is still 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.)

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.

-- 
Anders

---

From: Kristian Ølgaard <[email-masked]>
Date: Thu, 21 Oct 2010 11:35:33 +0200

On 21 October 2010 11:01, Anders Logg <[email-masked]> wrote:
> I found the notes I made. Most issues have already been fixed, but here are
> some more that need fixing:
>
> 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.

> * The Launchpad pages page is still missing

The page is there, but the links are missing.

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

---

From: Kristian Ølgaard <[email-masked]>
Date: Thu, 21 Oct 2010 11:47:46 +0200

>> fixed and also be noted in the style guide.

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

---

From: Anders Logg <[email-masked]>
Date: Thu, 21 Oct 2010 12:28:45 +0200

Kristian Ølgaard skrev 2010-10-21 11.47:
> On 21 October 2010 11:35, Kristian Ølgaard<[email-masked]>  wrote:
>> On 21 October 2010 11:01, Anders Logg<[email-masked]>  wrote:

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.

>> OK, perhaps we can include it in the common section?

Sounds good.

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

-- 
Anders

---

From: Kristian Ølgaard <[email-masked]>
Date: Thu, 21 Oct 2010 15:06:49 +0200

On 21 October 2010 12:28, Anders Logg <[email-masked]> wrote:
>>>> at,
> 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 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.

>>> OK, perhaps we can include it in the common section?

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.

> 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

---

From: Anders Logg <[email-masked]>
Date: Mon, 25 Oct 2010 09:49:08 +0200

> I changed it to lowercase.

Great.

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

> looks. If we're happy I can add the rest and include some appropriate

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.

> presented in this thread.

ok!

--
Anders

---

From: Kristian Ølgaard <[email-masked]>
Date: Mon, 25 Oct 2010 12:40:52 +0200

> Looks good. There are some inconsistencies wrt use of ':' or not.

Fixed.

> on each line after the mailing lists?

Good idea, I added this.

> 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