dolfin team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Tue, Aug 31, 2010 at 11:08:01AM +0200, Kristian Ølgaard wrote:
> On 31 August 2010 10:59, Anders Logg <logg@xxxxxxxxx> wrote:
> > Kristian, is it ok if I reorganize the demo doc files somewhat?
> >
> > I think it would be more practical to have
> >
> >  demo/pde/poisson/cpp/{index.rst, main.cpp, ...}
> >  demo/pde/poisson/python/{index.rst, demo.py, ...}
> >  demo/pde/poisson/common/{index.txt}
>
> Why the common/index.txt? Shouldn't it just be:
> poisson/poisson.txt (eqns. etc.)
> poisson/cpp/{poisson.rst, main.cpp}
> poisson/python/{poisson.rst, demo.py}
> ?

Yes, that's better. But isn't index.rst better than poisson.rst?
In the same way as we name all demos demo.py or main.cpp. Then
everyone knows what expect, like every demo should have a main.cpp and
an index.rst.

> > But the toctree layout remains the same. Or would the above break the
> > toctree? Is it linked to how we organize the directories?
>
> I think it should be possible, but where do you want to put
> demo/cpp/index.rst? The toctree in this file should then be
> reorganized of course.

I don't know, perhaps

  demo/index.rst
  demo/python.rst
  demo/cpp.rst

?

> > The reason for the above change is that it seems practical to keep the
> > C++ and Python versions of a demo close (on file, but they would be on
> > different pages in the documentation).
>
> Why is this practical? To keep the source tree identical to the
> dolfin/demo structure (which will be deleted soon anyway)?
> I just thought it was easier to split the two versions as early as
> possible since the documentation will be different anyway, but I won't
> object if you like to reorganize things.

I'm currently documenting a new demo and then I'm first doing one
language, then the other. I like to think of it as a package which
happens to come in two different flavors. If we split it up, there's a
greater chance the two versions will diverge.

--
Anders