Subject: [Fenics] FEniCS Documentation, file names

From: [email-masked]
Date: Tue, 27 Apr 2010 16:45:00 +0200 (CET)

Hello,

I think now is a good time to settle on a naming convention for the file names in the documentation source directory.
The naming is now inconsistent at best because I tried to give each file a unique name since we did not know how the directory structure should look like.

Now, for instance, we have (in source/):

./programmers-reference/appendices/appendices.rst   (index page for appendices)
./programmers-reference/appendices/ffc/ffc_index.rst (another index page)
./programmers-reference/appendices/ffc/ffc_introduction.rst

./demos/demos.rst (index page for demos)
./demos/cpp/cpp_demos.rst (another index page)
./demos/python/python_demos.rst (yet another index page)
./demos/cpp/pde/cpp_poisson.rst (C++ version of Poisson)
./demos/cpp/pde/Poisson.ufl
./demos/cpp/pde/poisson_main.cpp
./demos/python/pde/python_poisson.rst (Python version of Poisson)
./demos/common/pde/poisson.txt

Would it be better to simply skip all cpp_ and python_ (should be clear from the path) and simply use index.rst for index pages?
We should probably also insert one more level in the demos directory such that demos/cpp/pde/cpp_poisson.rst --> demos/cpp/pde/poisson/poisson.rst

Then the names would be:

./programmers-reference/appendices/index.rst
./programmers-reference/appendices/ffc/index.rst
./programmers-reference/appendices/ffc/introduction.rst

./demos/index.rst
./demos/cpp/index.rst
./demos/python/index.rst
./demos/cpp/pde/poisson/poisson.rst
./demos/cpp/pde/poisson/Poisson.ufl
./demos/cpp/pde/poisson/main.cpp
./demos/python/pde/python/poisson.rst
./demos/common/pde/poisson/equations.txt
./demos/common/pde/poisson/results.txt   (if we want to show some results too, we can also share that)
./demos/common/pde/poisson/results.png

It might be confusing to have a lot of files opened that all have the name 'index.rst', but the names will be a lot shorter.

Kristian

---

From: "Garth N. Wells" <[email-masked]>
Date: Wed, 28 Apr 2010 10:53:09 +0100

On 27/04/10 15:45, [email-masked] wrote:
>
> Hello,
>
> I think now is a good time to settle on a naming convention for the file
> names in the documentation source directory.
> The naming is now inconsistent at best because I tried to give each file
> a unique name since we did not know how the directory structure should
> look like.
>
> Would it be better to simply skip all cpp_ and python_ (should be clear
> from the path) and simply use index.rst for index pages?

I'm not too fussed about this.

> We should probably also insert one more level in the demos directory
> such that demos/cpp/pde/cpp_poisson.rst -->
> demos/cpp/pde/poisson/poisson.rst
>

Agree.

Garth

> It might be confusing to have a lot of files opened that all have the
> name 'index.rst', but the names will be a lot shorter.
>
> Kristian
>
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : [email-masked]
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp

---

From: Anders Logg <[email-masked]>
Date: Wed, 28 Apr 2010 18:28:05 +0200

> It might be confusing to have a lot of files opened that all have the name 'index.rst', but the names will be a lot shorter.

This seems the best solution. It's also how we've done it before. All
the demos are named 'demo.py' or 'main.cpp'/'demo'.

But why should it be

and not

  ./demos/cpp/pde/poisson/index.rst

?

--
Anders

---

From: Kristian Oelgaard <[email-masked]>
Date: Wed, 28 Apr 2010 18:41:50 +0200 (CET)

>  ./demos/cpp/pde/poisson/index.rst

because the contents in poisson.rst is the text for the (C++) Poisson demo, it is not an index page since it doesn't contain the .. toctree:: directive.
I thought it would be nice to be able to guess the content of the file by the name before opening them.

Kristian

> ?
>
> --
> Anders
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
>
> iEYEARECAAYFAkvYYhUACgkQTuwUCDsYZdHvRgCfYrCQ6JBbBKmat3KBM4kUhKzz
> R5AAnA4VkJtrDWiW2nTxPYgsUdr2NFmL
> =yxm2
> -----END PGP SIGNATURE-----
>
>