Subject: [Fenics] FEniCS documentation

From: [email-masked]
Date: Fri, 16 Apr 2010 17:15:52 +0200 (CET)

Hello,

I've started setting up the files for the FEniCS documentation.
Try:

bzr branch lp:fenics-doc
cd fenics-doc
make html
your-favorite-web-browser build/html/index.html

to see the result. Everything is up for discussion and comments/suggestions are welcome.

I also added some more detailed blueprints at:

https://blueprints.launchpad.net/fenics-doc

have a look and feel free to join the discussion or sign up for a blueprint.

One question though, where do we publish the HTML/PDF files that are generated?
I guess we should put them where

http://new.fenics.org/Main_Page

is located and then link to the index.html page?

Kristian

---

From: Anders Logg <[email-masked]>
Date: Sat, 17 Apr 2010 20:04:41 +0200

> is located and then link to the index.html page?

It looks like a good start. Here are some initial comments:

1. The default Sphinx theme looks really good. But I suspect we will
want to theme it to match the new redesigned web pages (in progress).
Harish can comment on this.

2. I'm not sure where to put things on the server. There are two
possible locations in the new content tree Harish has sketched out:

  User - Using
  Developer - Documentation

What you are writing is a little bit of both. Perhaps it should be
split up. Opinions?

For now, we can just put it somewhere for people to look at what's
going on, like www.fenics.org/newdoc.

Johannes, could you set up a cronjob on the server to pull the manual,
generate it and copy the files to that location?

3. It looks suboptimal to have Tutorial and User Manual as part of the
documentation tree. I think Tutorial and User Manual should be two
different documents (linked from some other HTML page). And most of
what you have in the top list right now (introduction, installation,
contributing, guidelines, appendices) should then be part of the user
manual. The table of contents of the user manual could be similar to
what we have now in the old DOLFIN user manual:

  introductioin
  installation
  linear algebra
  meshes
  ...
  contributing
  ...

Or is it better to have a third document: programmer's reference?

4. Let's keep the discussion regarding the documentation open here on
this list.

--
Anders

---

From: Johannes Ring <[email-masked]>
Date: Mon, 19 Apr 2010 10:48:17 +0200

> generate it and copy the files to that location?

Done.

Johannes

> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
>
> iEYEARECAAYFAkvJ+DQACgkQTuwUCDsYZdHHIwCfUNTqgjhT/WpexaDdIRlVvuKR
> nIkAnROeJ62tDTQH4h3JDBJ+JcEmTm6T
> =eb8R
> -----END PGP SIGNATURE-----
>
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : [email-masked]
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp
>
>

---

From: Kristian Oelgaard <[email-masked]>
Date: Mon, 19 Apr 2010 10:53:58 +0200 (CET)

> Harish can comment on this.

Sounds reasonable, from the files it looks like it's just a matter of supplying the template somehow.

> what we have now in the old DOLFIN user manual:

I agree that the Tutorial and User Manual should probably have their separate build directory.
Then the PDF versions of the Tutorial and User Manual will also be separated in a simple way.
(Personally, I don't see why anyone will ever use the PDF version of the User Manual if the HTML version is available.)

However, w.r.t. the introduction, installation, contributing and guidelines (I agree that appendices should be in the User Manual) I was trying to put things in a larger perspective such that the FEniCS Documentation (the main page) explains the three ways that we offer help to our users:

1. Tutorial (a quick overview)
2. User Manual (which I think will be more of a DOLFIN programmer's reference)
3. Demos (code that users can copy and modify to get started)

I guess these 3 parts should be in separate directories and then linked to from the main page.

The installation section should then cover the minimal installation of FEniCS projects which is needed to run all code presented in the documentation.

Since all FEniCS projects are managed in the same way on Launchpad, I thought it was a good idea to have a general page on how to contribute to FEniCS. That will allow us to make the procedure for merging, patching etc. more uniform across projects.

My intention with the guidelines page is to have a list of specifications that should be followed to ensure a uniform documentation, it is thus only concerned with the documentation pages.

>  introductioin

Yes, each part (Tutorial, User Manual, Demos) should have an introduction that explains the purpose of what follows.

>  installation

I was hoping to handle this on the 'global level' as explained above.

>  contributing

Again, I was hoping to handle this on the 'global level' as explained above.

  ...
> Or is it better to have a third document: programmer's reference?

Or rename User Manual to Programmer's Reference?

> 4. Let's keep the discussion regarding the documentation open here on

Sure.

Kristian

---

From: Anders Logg <[email-masked]>
Date: Mon, 19 Apr 2010 21:43:55 +0200

> (Personally, I don't see why anyone will ever use the PDF version of the User Manual if the HTML version is available.)

Me neither but it might be good to have the possibility of printing
the manual if needed.

> My intention with the guidelines page is to have a list of
> specifications that should be followed to ensure a uniform
> documentation, it is thus only concerned with the documentation
> pages.

Perhaps Python is a good model to follow, see
http://www.python.org/doc/.  It's kind of similar to what you have
now, but what you have named User Manual is called Library Reference /
Language Reference. They have Tutorial as one item in the table of
contents but there are advantages to having it in a separate document
(so it can be printed).

How about this:

  Tutorial (one document)

  User manual (a second document)
    Introduction
    Installation
    Library reference (documenting the API)
    Contributing
    Guidelines
    Appendices

  Demos (a third document)
    Overview
    Linear algebra
      Name of demo
      Name of demo
      ...
    Meshes
      Name of demo
      ...

--
Anders

---

From: "Garth N. Wells" <[email-masked]>
Date: Tue, 20 Apr 2010 08:46:16 +0400

> I've started setting up the files for the FEniCS documentation.

A changes sent to a mailing list?

Garth

---

From: Anders Logg <[email-masked]>
Date: Tue, 20 Apr 2010 08:51:30 +0200

> A changes sent to a mailing list?

I have added FEniCS core team as a subscriber but everyone can
subscribe here:

  https://code.launchpad.net/~fenics-core/fenics-doc/main

--
Anders

---

From: Kristian Oelgaard <[email-masked]>
Date: Tue, 20 Apr 2010 10:16:27 +0200 (CET)

>    Library reference (documenting the API)

If we use Python as a model, Installation, Contributing, Guidelines should be moved one level up.
See  http://docs.python.org/index.html.
I'm creating a separate page that can work as an overview of the documentation we have a available. It will contain external links to Tutorial, User manual, Demos and thus work in much the same way as the Python index page. Let's see how it looks and works.

>      Name of demo

Agree.

Kristian

> iEYEARECAAYFAkvMsnsACgkQTuwUCDsYZdHfiQCfVg6rnD3KH테葋徍﷋�
> UY0An2YvJNlHneJaWIF4Fy2svkDTwzFA
> =YWVx

---

From: Anders Logg <[email-masked]>
Date: Tue, 20 Apr 2010 12:58:15 +0200

> I'm creating a separate page that can work as an overview of the documentation we have a available. It will contain external links to Tutorial, User manual, Demos and thus work in much the same way…

ok, sounds good.

--
Anders

---

From: Kristian Oelgaard <[email-masked]>
Date: Mon, 26 Apr 2010 11:06:52 +0200 (CET)

> what we have now in the old DOLFIN user manual:

After some more digging around I found that NOT having the different parts in the same documentation tree seems suboptimal, since having all files in the same tree makes it very easy to cross reference and link between the parts. I imagine that we want to link heavily between the User Manual and Demos (Perhaps also the Tutorial).
Sphinx makes it very easy to build separate PDFs for for the individual parts like C++ Tutorial, Python Tutorial, C++ Demos etc. so that shouldn't be a problem.

Kristian

---

From: Anders Logg <[email-masked]>
Date: Mon, 26 Apr 2010 13:29:42 +0200

> Sphinx makes it very easy to build separate PDFs for for the individual parts like C++ Tutorial, Python Tutorial, C++ Demos etc. so that shouldn't be a problem.

ok, as long as the entry page looks logical.

--
Anders

---

From: Kristian Oelgaard <[email-masked]>
Date: Mon, 26 Apr 2010 18:40:24 +0200 (CET)

> ok, as long as the entry page looks logical.

I moved things back to how they were (one top directory) and set up a build for separate PDFs for each sup part of the documentation.
Run the build_docs script and view the result in build/html/index.html.

Johannes, you should probably run this script too on the server to generate the PDFs before the HTML pages.

Kristian

> iEYEARECAAYFAkvVeSYACgkQTuwUCDsYZdE+EQCdHyOGgTfzoBKnRBjglxcp2pMG
> aq0An0X5jwQ2EK8xYcGI9XyhhIwY3xXR
> =hUxZ

---

From: Johannes Ring <[email-masked]>
Date: Tue, 27 Apr 2010 09:01:15 +0200

On Mon, Apr 26, 2010 at 6:40 PM, Kristian Oelgaard
<[email-masked]> wrote:
>>> After some more digging around I found that NOT having the different
>>> parts in the same documentation tree seems suboptimal, since having all
>>> files in the same tree makes it very easy to cross reference and link
>>> between the parts. I imagine that we want to link heavily between the User
>>> Manual and Demos (Perhaps also the Tutorial).
>>> Sphinx makes it very easy to build separate PDFs for for the individual
>>> parts like C++ Tutorial, Python Tutorial, C++ Demos etc. so that shouldn't
>>> be a problem.
>>
> I moved things back to how they were (one top directory) and set up a build
> for separate PDFs for each sup part of the documentation.

Done.

Johannes

---

From: Anders Logg <[email-masked]>
Date: Tue, 27 Apr 2010 09:51:46 +0200

I think the new structure looks very good. A couple of suggestions:

1. Perhaps "Documenting FEniCS" should be part of "Contributing to
FEniCS"? It seems it otherwise gets a too prominent place in the
overview. I expect there will be very few people interested in
knowing how to write documentation (unfortunately).

2. Should "User Manual" be renamed "Programmer's reference?"

--
Anders

---

From: Kristian Oelgaard <[email-masked]>
Date: Tue, 27 Apr 2010 10:15:21 +0200 (CET)

> knowing how to write documentation (unfortunately).

Which I why I decided to promote it on the front page! :)
But I agree that it fits more naturally in the Contributing part.
I'll move it.

> 2. Should "User Manual" be renamed "Programmer's reference?"

Yes, I think that is a better name for what it really is (will be).

Kristian

> iEYEARECAAYFAkvWl5EACgkQTuwUCDsYZdHt8gCfTfX69EwA3KLVZ2z0ziludHuE
> xLMAn1eslsrRAnQR/c/MNiFodROAYR+o
> =nlud

---

From: Anders Logg <[email-masked]>
Date: Tue, 27 Apr 2010 11:29:21 +0200

> Yes, I think that is a better name for what it really is (will be).

ok, great.

Now we just need some contents...

--
Anders

---

From: Kristian Oelgaard <[email-masked]>
Date: Tue, 27 Apr 2010 11:40:35 +0200 (CET)

> Now we just need some contents...

Agree, I pushed the above changes.

Kristian

> iEYEARECAAYFAkvWrnAACgkQTuwUCDsYZdFUpwCfWLuTe+OD6eBST4E7cmv5S4zy
> 0+UAnR7qBlPy6k7hK+iymNfGagXkQ6Cd
> =EN7E

---

From: Nathan Borggren <[email-masked]>
Date: Wed, 28 Apr 2010 11:40:11 -0400

Hello,
     If anybody is interested I'd be willing to help with some documentation
efforts.  My background is in math and physics and tend to work exclusively
on the python end of things when computers get involved.  I've been working
with FEniCS for maybe a month or two so am rather a novice on that end but
nonetheless I've been using python and doing functional analysis for a long
time and perhaps could contribute.  If some of the demos need transcriptions
to a latex readable/physicist readable format like the new Poisson
documentation I could be of aid.  I'm currently working with diffusion
equations and could help in that direction particularly.  How could I lend a
hand?
       Nathan Borggren

On Tue, Apr 27, 2010 at 5:29 AM, Anders Logg <[email-masked]> wrote:

> Mailing list: https://launchpad.net/~fenics<https://launchpad.net/%7Efenics>
> Unsubscribe : https://launchpad.net/~fenics<https://launchpad.net/%7Efenics>

---

From: Anders Logg <[email-masked]>
Date: Wed, 28 Apr 2010 18:13:58 +0200

Sounds good, I hope Kristian can give you some instructions on what
you can help out with.

--
Anders

On Wed, Apr 28, 2010 at 11:40:11AM -0400, Nathan Borggren wrote:
> efforts.  My background is in math and physics and tend to work exclusively on
> the python end of things when computers get involved.  I've been working with
> FEniCS for maybe a month or two so am rather a novice on that end but
> time and perhaps could contribute.  If some of the demos need transcriptions to
> a latex readable/physicist readable format like the new Poisson documentation I
> could be of aid.  I'm currently working with diffusion equations and could help
> in that direction particularly.  How could I lend a hand?
>        Nathan Borggren
>

---

From: Kristian Oelgaard <[email-masked]>
Date: Wed, 28 Apr 2010 18:33:36 +0200 (CET)

> Sounds good, I hope Kristian can give you some instructions on what

Sure, we're still in the process of figuring out exactly how the format should be, but I think the demos might be the easiest place to start. Do we want to recategorize the demos as suggested in the blueprint, or should we just start adding all the demos that we have in DOLFIN and keep the directory structure?
Either way, it might be a good idea to start looking at the documentation that we have now for the Poisson equation, then we can work on getting that in good shape (both C++ and Python) so we can work out a good framework for documenting the other demos.

You can also have  a look at https://blueprints.launchpad.net/fenics-doc where I put some initial thoughts about what we need, and then of course joining the discussion here on the list is also an important way to help out.

Kristian

>>     >
>>     >
>>     > On 27 April 2010 09:51, Anders Logg <[email-masked]> wrote:
>>     > >I think the new structure looks very good. A couple of suggestions:
>>     > >
>>     > >1. Perhaps "Documenting FEniCS" should be part of "Contributing to
>>     > >FEniCS"? It seems it otherwise gets a too prominent place in the
>>     > >overview. I expect there will be very few people interested in
>>     > >knowing how to write documentation (unfortunately).
>>     >
>>     > Which I why I decided to promote it on the front page! :)
>>     > But I agree that it fits more naturally in the Contributing part.
>>     > I'll move it.
>>     >
>>     > >2. Should "User Manual" be renamed "Programmer's reference?"
>>     >
>>     > Yes, I think that is a better name for what it really is (will be).
>>     >
>>     > Kristian
>>
>>     ok, great.
>>
> iEYEARECAAYFAkvYXsYACgkQTuwUCDsYZdEm1gCgixVFogSvEHyRvzkxoyIjVVdt
> bKkAn3TrlvL8QYbUeQyAw5Qle+l/zmdE
> =FFok

---

From: Anders Logg <[email-masked]>
Date: Wed, 28 Apr 2010 18:41:21 +0200

On Wed, Apr 28, 2010 at 06:33:36PM +0200, Kristian Oelgaard wrote:
> Sure, we're still in the process of figuring out exactly how the
> format should be, but I think the demos might be the easiest place
> to start. Do we want to recategorize the demos as suggested in the
> blueprint, or should we just start adding all the demos that we have
> in DOLFIN and keep the directory structure?

I think some recategorization is necessary, but I don't know which is
best: to first add them and then move them around of first decide on
the categories and then add the demos.

Have you planned which categories should go into the programmer's
reference? We should probably try to match those categories with the
demos and link to them.

> Either way, it might be a good idea to start looking at the
> documentation that we have now for the Poisson equation, then we can
> work on getting that in good shape (both C++ and Python) so we can
> work out a good framework for documenting the other demos.

Yes. Let's all help out with the Poisson demo documentation and then
when everyone is happy we have a good template.

--
Anders

---

From: Kristian Oelgaard <[email-masked]>
Date: Wed, 28 Apr 2010 18:46:00 +0200 (CET)

> the categories and then add the demos.

Maybe we don't need to add all of them before we have a better idea about the categories.
I don't think we'll get it right the first time anyway though.

> reference? We should probably try to match those categories with the

No, not yet, but I think the structure in the DOLFIN source tree is pretty logical.
The question is if we can match everything up with a demo, although it would be nice if we could.

Kristian

> iEYEARECAAYFAkvYZTEACgkQTuwUCDsYZdE+eQCeNw8+Ux6OENggxYFK1ibQCHkH
> 3QcAn1X1GKfvx75Ptyfb4S6dGWca19eS
> =KQLR

---

From: "Garth N. Wells" <[email-masked]>
Date: Thu, 29 Apr 2010 14:21:49 +0100

> would be nice if we could.

I'm not so sure that this is possible/sensible. The demos 'demonstrate' 
how to solve various problems and how to use various features. Shouldn't 
the programmers reference document the interface?

Garth

>>> You can also have  a look at
>>> https://blueprints.launchpad.net/fenics-doc where I put some initial
>>> thoughts about what we need, and then of course joining the
>>> discussion here on the list is also an important way to help out.
>>>
>>> Kristian
>>>
>>> >--
>>> >Anders
>>> >
>>> >

---

From: Kristian Oelgaard <[email-masked]>
Date: Thu, 29 Apr 2010 15:35:45 +0200 (CET)

On 29 April 2010 15:21, Garth N. Wells <[email-masked]> wrote:
> I'm not so sure that this is possible/sensible. The demos 'demonstrate' how
> to solve various problems and how to use various features. Shouldn't the
> programmers reference document the interface?

Yes, the programmer's reference should document *everything* in the interface, and when documenting for instance the
NewtonSolver there should probably also be some short example code, but it would be nice to link to a few of the demos that use the feature to solve something real. This is surely not possible in all cases but whenever it makes sense I think it is a good idea.

Kristian

---

From: "Garth N. Wells" <[email-masked]>
Date: Thu, 29 Apr 2010 14:37:58 +0100

On 29/04/10 14:35, Kristian Oelgaard wrote:
> Yes, the programmer's reference should document *everything* in the
> interface, and when documenting for instance the
> NewtonSolver there should probably also be some short example code, but
> it would be nice to link to a few of the demos that use the feature to
> solve something real. This is surely not possible in all cases but
> whenever it makes sense I think it is a good idea.
>

OK. This sounds along the same lines as the PETSc online docs 
(documentation of basic functions have a link to numerous demos at the 
bottom of the page, and more advanced functions have few or no demos).

Garth

---

From: Anders Logg <[email-masked]>
Date: Thu, 29 Apr 2010 15:43:14 +0200

On Thu, Apr 29, 2010 at 02:21:49PM +0100, Garth N. Wells wrote:
> I'm not so sure that this is possible/sensible. The demos
> 'demonstrate' how to solve various problems and how to use various
> features. Shouldn't the programmers reference document the
> interface?

I think there's also room for simple demos that illustrate the use
of basic classes like Mesh, MeshFunction, input/output, linear
algebra, parameters etc like we have now, without necessarily solving
a PDE.

--
Anders

---

From: "Garth N. Wells" <[email-masked]>
Date: Thu, 29 Apr 2010 14:48:16 +0100

On 29/04/10 14:43, Anders Logg wrote:
>>> On 28 April 2010 18:41, Anders Logg<[email-masked]>  wrote:
>>>>> On 28 April 2010 18:13, Anders Logg<[email-masked]>  wrote:

Yes, these demonstrate various 'features'.

Garth

---

From: Kristian Oelgaard <[email-masked]>
Date: Thu, 29 Apr 2010 15:49:30 +0200 (CET)

> algebra, parameters etc like we have now, without necessarily solving

Yes, sure. The example code in the programmer's reference should just cover one function and the immediate usage, but then we can link to a demo that puts the use in a more elaborate context.

Kristian

> iEYEARECAAYFAkvZjPIACgkQTuwUCDsYZdEJ3QCcCj9scIsniFgMDBtBlwrI+Akg
> RE8AnAnTt1a+079P5fwQXTUQgMDeKYyK
> =3++r

---

From: Anders Logg <[email-masked]>
Date: Thu, 29 Apr 2010 15:50:59 +0200

> Yes, these demonstrate various 'features'.

ok.

--
Anders

---

From: Anders Logg <[email-masked]>
Date: Thu, 29 Apr 2010 15:52:15 +0200

> Yes, sure. The example code in the programmer's reference should just cover one function and the immediate usage, but then we can link to a demo that puts the use in a more elaborate context.

I guess the difference is that the programmer's reference can contain
code snippets (which probably won't run without extra stuff added) but
the demos must be stand-alone programs that do all that extra stuff
(like actually creating a mesh before using it).

--
Anders

---

From: Kristian Oelgaard <[email-masked]>
Date: Thu, 29 Apr 2010 15:55:36 +0200 (CET)

> (like actually creating a mesh before using it).

Yes, exactly. That's a good definition, let's stick to that.

Kristian

> iEYEARECAAYFAkvZjw8ACgkQTuwUCDsYZdGNxACgmLUmNJRdtnaQ8kggOLmu/rMH
> FMQAoJfr9zTD3S44JRUtQLrP2PPU18b3
> =0WnK