Subject: Re: [Fenics] [Branch ~fenics-core/fenics-doc/main] Rev 68: Add empty pages for all libraries. Will clean up later (yes I know the labels should be unique).

From: Kristian Ølgaard <[email-masked]>
Date: Thu, 26 Aug 2010 16:04:39 +0200

Before adding contents to these pages we should agree if we're happy
with the current layout/format of the programmer's reference part of
the documentation.
I just finished a first iteration on the style guides for both C++ and
Python versions so have a look and see if it makes sense.

I'll start integrating the documentation with DOLFIN such that we have
the updated docstrings for the Python module.
Do we want to distribute the entire pseudo module containing the
docstrings with DOLFIN or just enough to avoid crashing the import and
then relying on the user having FEniCS documentation installed. The
latter is possible if we run the dolfin/swig/generate.py script as
part of the build process.

Kristian

On 26 August 2010 15:39,  <[email-masked]> wrote:
> ------------------------------------------------------------
> revno: 68
> committer: Anders Logg <[email-masked]>
> branch nick: fenics-doc
> timestamp: Thu 2010-08-26 15:36:13 +0200
> message:
>  Add empty pages for all libraries. Will clean up later (yes I know the labels should be unique).
> added:
>  source/programmers-reference/cpp/adaptivity/
>  source/programmers-reference/cpp/adaptivity/index.rst
>  source/programmers-reference/cpp/ale/
>  source/programmers-reference/cpp/ale/index.rst
>  source/programmers-reference/cpp/common/
>  source/programmers-reference/cpp/common/index.rst
>  source/programmers-reference/cpp/fem/
>  source/programmers-reference/cpp/fem/index.rst
>  source/programmers-reference/cpp/function/
>  source/programmers-reference/cpp/function/index.rst
>  source/programmers-reference/cpp/graph/
>  source/programmers-reference/cpp/graph/index.rst
>  source/programmers-reference/cpp/io/
>  source/programmers-reference/cpp/io/index.rst
>  source/programmers-reference/cpp/la/
>  source/programmers-reference/cpp/la/index.rst
>  source/programmers-reference/cpp/log/
>  source/programmers-reference/cpp/log/index.rst
>  source/programmers-reference/cpp/math/
>  source/programmers-reference/cpp/math/index.rst
>  source/programmers-reference/cpp/nls/
>  source/programmers-reference/cpp/nls/index.rst
>  source/programmers-reference/cpp/ode/
>  source/programmers-reference/cpp/ode/index.rst
>  source/programmers-reference/cpp/parameter/
>  source/programmers-reference/cpp/parameter/index.rst
>  source/programmers-reference/cpp/plot/
>  source/programmers-reference/cpp/plot/index.rst
>  source/programmers-reference/cpp/quadrature/
>  source/programmers-reference/cpp/quadrature/index.rst
> modified:
>  source/programmers-reference/cpp/index.rst
>
>
> --
> lp:fenics-doc
> https://code.launchpad.net/~fenics-core/fenics-doc/main
>
> You are subscribed to branch lp:fenics-doc.
> To unsubscribe from this branch go to https://code.launchpad.net/~fenics-core/fenics-doc/main/+edit-subscription
>
> === added directory 'source/programmers-reference/cpp/adaptivity'
> === added file 'source/programmers-reference/cpp/adaptivity/index.rst'
> --- source/programmers-reference/cpp/adaptivity/index.rst       1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/adaptivity/index.rst       2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
> === added directory 'source/programmers-reference/cpp/ale'
> === added file 'source/programmers-reference/cpp/ale/index.rst'
> --- source/programmers-reference/cpp/ale/index.rst      1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/ale/index.rst      2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
> === added directory 'source/programmers-reference/cpp/common'
> === added file 'source/programmers-reference/cpp/common/index.rst'
> --- source/programmers-reference/cpp/common/index.rst   1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/common/index.rst   2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
> === added directory 'source/programmers-reference/cpp/fem'
> === added file 'source/programmers-reference/cpp/fem/index.rst'
> --- source/programmers-reference/cpp/fem/index.rst      1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/fem/index.rst      2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
> === added directory 'source/programmers-reference/cpp/function'
> === added file 'source/programmers-reference/cpp/function/index.rst'
> --- source/programmers-reference/cpp/function/index.rst 1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/function/index.rst 2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
> === added directory 'source/programmers-reference/cpp/graph'
> === added file 'source/programmers-reference/cpp/graph/index.rst'
> --- source/programmers-reference/cpp/graph/index.rst    1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/graph/index.rst    2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
> === modified file 'source/programmers-reference/cpp/index.rst'
> --- source/programmers-reference/cpp/index.rst  2010-08-26 12:41:15 +0000
> +++ source/programmers-reference/cpp/index.rst  2010-08-26 13:36:13 +0000
> @@ -12,6 +12,19 @@
>  .. toctree::
>     :maxdepth: 1
>
> -    :ref:`testing <programmers_reference_cpp_mesh_index>`
> -
> -    mesh/index
> +    Adaptivity <adaptivity/index>
> +    Finite elements <fem/index>
> +    Functions and function spaces <function/index>
> +    Graphs <graph/index>
> +    Input / output <io/index>
> +    Linear algebra <la/index>
> +    Log system <log/index>
> +    Mathematical functions <math/index>
> +    Meshes <mesh/index>
> +    Moving meshes <ale/index>
> +    Nonlinear solvers <nls/index>
> +    Numerical quadrature <quadrature/index>
> +    ODE solvers <ode/index>
> +    Parameter system <parameter/index>
> +    Plotting <plot/index>
> +    Utilities <common/index>
>
> === added directory 'source/programmers-reference/cpp/io'
> === added file 'source/programmers-reference/cpp/io/index.rst'
> --- source/programmers-reference/cpp/io/index.rst       1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/io/index.rst       2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
> === added directory 'source/programmers-reference/cpp/la'
> === added file 'source/programmers-reference/cpp/la/index.rst'
> --- source/programmers-reference/cpp/la/index.rst       1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/la/index.rst       2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
> === added directory 'source/programmers-reference/cpp/log'
> === added file 'source/programmers-reference/cpp/log/index.rst'
> --- source/programmers-reference/cpp/log/index.rst      1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/log/index.rst      2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
> === added directory 'source/programmers-reference/cpp/math'
> === added file 'source/programmers-reference/cpp/math/index.rst'
> --- source/programmers-reference/cpp/math/index.rst     1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/math/index.rst     2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
> === added directory 'source/programmers-reference/cpp/nls'
> === added file 'source/programmers-reference/cpp/nls/index.rst'
> --- source/programmers-reference/cpp/nls/index.rst      1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/nls/index.rst      2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
> === added directory 'source/programmers-reference/cpp/ode'
> === added file 'source/programmers-reference/cpp/ode/index.rst'
> --- source/programmers-reference/cpp/ode/index.rst      1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/ode/index.rst      2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
> === added directory 'source/programmers-reference/cpp/parameter'
> === added file 'source/programmers-reference/cpp/parameter/index.rst'
> --- source/programmers-reference/cpp/parameter/index.rst        1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/parameter/index.rst        2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
> === added directory 'source/programmers-reference/cpp/plot'
> === added file 'source/programmers-reference/cpp/plot/index.rst'
> --- source/programmers-reference/cpp/plot/index.rst     1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/plot/index.rst     2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
> === added directory 'source/programmers-reference/cpp/quadrature'
> === added file 'source/programmers-reference/cpp/quadrature/index.rst'
> --- source/programmers-reference/cpp/quadrature/index.rst       1970-01-01 00:00:00 +0000
> +++ source/programmers-reference/cpp/quadrature/index.rst       2010-08-26 13:36:13 +0000
> @@ -0,0 +1,15 @@
> +.. Index file for the mesh directory.
> +
> +.. _programmers_reference_cpp_mesh_index:
> +
> +****
> +mesh
> +****
> +
> +This is the index page for files in the directory dolfin/mesh:
> +
> +.. toctree::
> +    :maxdepth: 2
> +
> +    Mesh
> +
>
>
>

---

From: Anders Logg <[email-masked]>
Date: Thu, 26 Aug 2010 17:41:54 +0200

> with the current layout/format of the programmer's reference part of

I'll take a look.

> Python versions so have a look and see if it makes sense.

ok.

> part of the build process.

Why would it be a problem to distribute the entire pseudo module? Is
it big?

--
Anders

> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : [email-masked]
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp

--
Anders

---

From: Kristian Ølgaard <[email-masked]>
Date: Thu, 26 Aug 2010 17:50:07 +0200

>> with the current layout/format of the programmer's reference part of

Thanks.

> Why would it be a problem to distribute the entire pseudo module? Is

No, I just didn't want to flood the repository with a bunch of files
which are essentially copies.

So we'll just update the docstrings module like we do now for the
docstrings.i file (which will also be updated by running the
generate.py script).

Kristian