dolfin team mailing list archive

[Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx>]

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}

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

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
>