fenics team mailing list archive

[Kristian Oelgaard <k.b.oelgaard@xxxxxxxxx>]

On 27 April 2010 11:41, Garth N. Wells <gnw20@xxxxxxxxx> wrote:
> On 27/04/10 10:32, Anders Logg wrote:
> > On Tue, Apr 27, 2010 at 10:28:13AM +0100, Garth N. Wells wrote:
> > > On 27/04/10 10:11, Kristian Oelgaard wrote:
> > > > On 27 April 2010 10:50, Garth N. Wells<gnw20@xxxxxxxxx>  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.
> > >
> > > 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).
>
> At present, it doesn't come from a common source. That's my point.

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

> Garth
>
> > 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
> >
> >
> > > 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
> > > >
> > > > > 1. Problem and method description
> > > > > 2. Documentation of C++ demo code
> > > > > 3. Documentation of Python demo code
> > > > >
> > > > > Garth
> > > > >
> > > > > _______________________________________________
> > > > > Mailing list: https://launchpad.net/~fenics
> > > > > Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> > > > > Unsubscribe : https://launchpad.net/~fenics
> > > > > More help   : https://help.launchpad.net/ListHelp
> > >
> > > _______________________________________________
> > > Mailing list: https://launchpad.net/~fenics
> > > Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> > > Unsubscribe : https://launchpad.net/~fenics
> > > More help   : https://help.launchpad.net/ListHelp

Attachment: signature.asc
Description: OpenPGP digital signature