dolfin team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Tue, Aug 31, 2010 at 11:23:10AM +0200, Kristian Ølgaard wrote:
> On 31 August 2010 11:12, Anders Logg <logg@xxxxxxxxx> wrote:
> > 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.
>
> I think of index.rst as something which contains a toctree (overview
> of a directory) and includes other rst files.
> The poisson.rst contains the source code for documentation of the
> Poisson demo. But maybe documentation.rst is better and rename
> poisson.txt --> common.txt while at it?
> Then we have:
> poisson/common.txt (eqns. etc.)
> poisson/cpp/{documentation.rst, main.cpp}
> poisson/python/{documentation.rst, demo.py}

That sounds good.

I'll finish up the demo I'm working on now (Navier-Stokes) and will
push that before I attempt any changes.

> >> > 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
>
> I think that could work yes with index.rst including python.rst and
> cpp.rst in the toctree.
> Then python.rst and cpp.rst have toctrees which includes only the
> relevant */cpp/documentation.rst and */python/documentation.rst files?

Sounds good.

--
Anders


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