Subject: [Fenics] Demo documentation

From: "Garth N. Wells" <[email-masked]>
Date: Tue, 27 Apr 2010 09:50:08 +0100

I'm wondering if it's appropriate to separate the documentation for 
demos into C++ and Python versions since a good fraction is common. We 
could combine it into one file, or split into three (rather than the two 
which we have now) with

1. Problem and method description
2. Documentation of C++ demo code
3. Documentation of Python demo code

Garth

---

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

On 27 April 2010 10:50, Garth N. Wells <[email-masked]> wrote:
> I'm wondering if it's appropriate to separate the documentation for demos
> into C++ and Python versions since a good fraction is common. We could
> combine it into one file, or split into three (rather than the two which we
> have now) with

I think it is a matter of taste. I was thinking that we could have the common text in separate *.rst files and then include them where appropriate in the C++ and Python specific files. Such that we have (in the demo dir):
common/*.rst
cpp/*.rst
python/*.rst

With this approach it will be possible to print a self contained version for either C++ or Python. It might not be very interesting for the demos, but the Tutorial and Programmer's reference could benefit from this approach.

Kristian

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

---

From: "Garth N. Wells" <[email-masked]>
Date: Tue, 27 Apr 2010 10:28:13 +0100

On 27/04/10 10:11, Kristian Oelgaard wrote:
> I think it is a matter of taste.

My point is not so much taste, but how best to avoid duplication. How 
can we best avoid duplicating the description of the equation and method?

Garth

> I was thinking that we could have the
> common text in separate *.rst files and then include them where
> appropriate in the C++ and Python specific files. Such that we have (in
> the demo dir):
> common/*.rst
> cpp/*.rst
> python/*.rst
>
> With this approach it will be possible to print a self contained version
> for either C++ or Python. It might not be very interesting for the
> demos, but the Tutorial and Programmer's reference could benefit from
> this approach.
>
> Kristian
>

---

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

On Tue, Apr 27, 2010 at 10:28:13AM +0100, Garth N. Wells wrote:
> My point is not so much taste, but how best to avoid duplication.
> How can we best avoid duplicating the description of the equation
> and method?

In this case, I think duplication is good, in particular since both
versions will originate from a common source (so there is really no
duplication).

I imagine it is easier for a Python user to click on a link for a demo
and get the full info on one page: the background/overview/equations
and the Python code.

The C++ user would get the same experience and the common intro is
just a separate file which gets included.

--
Anders

---

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

> just a separate file which gets included.

Yes, that is how I would like my own user experience to be.

Kristian

> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
>
> iEYEARECAAYFAkvWrzMACgkQTuwUCDsYZdEB1gCfXBWKJZjdiiUiiCBt/viPFoan
> t3IAn2ZK1vJEHn3mggp5CsmjYGCiMe4X
> =2t7n
> -----END PGP SIGNATURE-----
>
>

---

From: "Garth N. Wells" <[email-masked]>
Date: Tue, 27 Apr 2010 10:41:31 +0100

On 27/04/10 10:32, Anders Logg wrote:
>>> On 27 April 2010 10:50, Garth N. Wells<[email-masked]>  wrote:

At present, it doesn't come from a common source. That's my point.

Garth

---

From: Kristian Oelgaard <[email-masked]>
Date: Tue, 27 Apr 2010 12:39:04 +0200 (CET)

On 27 April 2010 11:41, Garth N. Wells <[email-masked]> wrote:
>>>>> demos

It does now :) let's see if this approach works out for us.
We're still in the process of figuring out best practices using Sphinx for our needs w.r.t. the documentation, but hopefully these discussions can help with that.

Kristian