fenics team mailing list archive

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

On 30 August 2010 14:41, Marie Rognes <meg@xxxxxxxxx> wrote:
> On 30. aug. 2010 14:34, Kristian Ølgaard wrote:
>> ---------- Forwarded message ----------
>> From: Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx>
>> Date: 30 August 2010 14:33
>> Subject: Re: [Branch ~fenics-core/fenics-doc/main] Rev 113: * Moved
>> "style guides"/"before committing" paragraphs to before
>> To: noreply@xxxxxxxxxxxxx
>>
>>
>> On 30 August 2010 14:02,  <noreply@xxxxxxxxxxxxx> wrote:
>>
>>> ------------------------------------------------------------
>>> revno: 113
>>> committer: Marie E. Rognes <meg@xxxxxxxxx>
>>> branch nick: fenics-doc
>>> timestamp: Mon 2010-08-30 13:53:09 +0200
>>> message:
>>>  * Moved "style guides"/"before committing" paragraphs to before
>>>    "creating patch/branch" in developer information
>>>
>>>  * Proof-read styleguides page.
>>>
>>>  Comments:
>>>
>>>  - This page is long. Maybe it could be split in two: a documenting
>>>    code and a documenting documentation page?
>>>
>> You mean the styleguide page? It's more formatting/layout than
>> documenting. The first part is how the format the C++ and Python
>> source code for DOLFIN, FFC, UFC, UFL etc. The second part is more of
>> a quick ref for reST and how to write documentation structure, what
>> directives to use and how.
>>
>>
>
>
> Yes, I did understand that :) However, the page is still long. Could it
> be split in its two parts?

The problem is in which toctree we should include it? I don't think we
can fit more on the front page without cluttering the layout, and
another 'index layer' in the styleguides is also not that elegant.

>>>  - The instructions about SConstruct file(s) must be updated -- see
>>>    warning.
>>>
>>>  - Marie does not understand this sentence (used twice):
>>>
>>>    "The functions are defined in the class body such that they
>>>     automatically have the Mesh namespace."
>>>
>> If in the .. cpp:class:: Mesh body you have a function definition ..
>> cpp:function:: coordinates(), the entry Mesh::coordinates() will be
>> added to the index and you should use :cpp:func:`Mesh::coordinates`
>> when referring to it.
>>
>>
>
>
> Ok! Maybe this sentence could be added?

Since it apparently helped clarify things for you it sounds like a good idea.

>
>>>  - Will the fact that the demos in the documentation compile and run be
>>>      tested automatically by the buildbot?  -- see note about this.
>>>
>> That is the idea once we have moved all demos to the documentation,
>> but the infrastructure is currently missing, we need to figure out
>> what is missing on the documentation side to enable the buildbots to
>> pick up the files/demos that needs testing.
>>
>>
>
> Ok -- once that is in place -- it would be good to replace the comment
> about "the demos should work with the current versions of the software"
> -- with "the demos are automatically tested against the current versions
> of the software".

Yes, and we should also figure out how to distribute documentation for
the stable releases.

Kristian

>
> --
> Marie
>
>> Kristian
>>
>>
>>> modified:
>>>  source/developer.rst
>>>  source/styleguides.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
>>>
>>> === modified file 'source/developer.rst'
>>> --- source/developer.rst        2010-08-27 12:30:42 +0000
>>> +++ source/developer.rst        2010-08-30 11:53:09 +0000
>>> @@ -165,6 +165,22 @@
>>>  <contributing_branches>`. If the code is accepted, the patch or branch
>>>  will be merged into the main branch by a member of the core team.
>>>
>>> +
>>> +Style guides
>>> +============
>>> +
>>> +To ease the job for maintainers that will need to read and understand
>>> +your code, read the :ref:`styleguides` that explain
>>> +how to format your code so that it matches the coding style used for
>>> +FEniCS.
>>> +
>>> +Before committing your work
>>> +===========================
>>> +
>>> +Before committing any contributions, make sure to test the code
>>> +thoroughly. This includes running any unit tests, regression tests
>>> +etc. present as part of the code you are modifying.
>>> +
>>>  .. _contributing_patches:
>>>
>>>  Creating a patch
>>> @@ -259,21 +275,6 @@
>>>  The procedure for using branches for other FEniCS components is
>>>  identical (with ``dolfin`` replaced by the relevant component name).
>>>
>>> -Style guides
>>> -============
>>> -
>>> -To ease the job for maintainers that will need to read and understand
>>> -your code, read the :ref:`styleguides` that explain
>>> -how to format your code so that it matches the coding style used for
>>> -FEniCS.
>>> -
>>> -Before committing your work
>>> -===========================
>>> -
>>> -Before committing any contributions, make sure to test the code
>>> -thoroughly. This includes running any unit tests, regression tests
>>> -etc. present as part of the code you are modifying.
>>> -
>>>  *********************
>>>  Writing documentation
>>>  *********************
>>>
>>> === modified file 'source/styleguides.rst'
>>> --- source/styleguides.rst      2010-08-26 16:36:47 +0000
>>> +++ source/styleguides.rst      2010-08-30 11:53:09 +0000
>>> @@ -158,7 +158,7 @@
>>>
>>>  Use ``dolfin::uint`` instead of ``int`` (unless you really want to use
>>>  negative integers). Use ``dolfin::real`` instead of ``double`` only if
>>> -you are sure that you want to exploit arbitray precision:
>>> +you are sure that you want to exploit arbitrary precision:
>>>
>>>  .. code-block:: c++
>>>
>>> @@ -168,7 +168,7 @@
>>>  Placement of brackets
>>>  ^^^^^^^^^^^^^^^^^^^^^
>>>
>>> -Curly brackets following multi-line control statements should appear
>>> +Curly brackets following multiline control statements should appear
>>>  on the next line and should not be indented:
>>>
>>>  .. code-block:: c++
>>> @@ -178,7 +178,7 @@
>>>       ...
>>>     }
>>>
>>> -For one line statements, ommit the brackets:
>>> +For one line statements, omit the brackets:
>>>
>>>  .. code-block:: c++
>>>
>>> @@ -267,10 +267,10 @@
>>>  ``<dolfin/dolfin_foo.h>`` inside the DOLFIN source tree. Only include
>>>  the portions of DOLFIN you are actually using.
>>>
>>> -Include as few header files a possible and use forward declarations
>>> +Include as few header files as possible and use forward declarations
>>>  whenever possible (in header files). Put the ``#include`` in the
>>> -implementation file.  This reduces compilation times and minimizes the
>>> -risk for cyclic dependencies.
>>> +implementation file.  This reduces compilation time and minimizes the
>>> +risk of cyclic dependencies.
>>>
>>>  Explicit constructors
>>>  ^^^^^^^^^^^^^^^^^^^^^
>>> @@ -321,11 +321,11 @@
>>>  Prefer smart pointers over plain pointers
>>>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>>
>>> -Use ``boost::shared_ptr`` and ``boost::scoped_ptr`` in favour or plain
>>> -pointers. Smart pointers reduce the likelihood of memory leaks and make
>>> -ownership clear.
>>> -Use ``scoped_ptr`` for a pointer which is not shared and
>>> -``shared_ptr`` when multiple pointers point to the same object.
>>> +Use ``boost::shared_ptr`` and ``boost::scoped_ptr`` in favour of plain
>>> +pointers. Smart pointers reduce the likelihood of memory leaks and
>>> +make ownership clear.  Use ``scoped_ptr`` for a pointer that is not
>>> +shared and ``shared_ptr`` when multiple pointers point to the same
>>> +object.
>>>
>>>
>>>  Python coding style
>>> @@ -340,12 +340,12 @@
>>>  Sphinx coding style
>>>  ===================
>>>
>>> -This style guide contains information on how to create documentation for
>>> -FEniCS using the Sphinx documentation tool. The first sections are related
>>> -to how the reST code should look like, then follows a section on frequently
>>> -used reST and Sphinx markup as a quick reference. The last two sections
>>> -are guides explaining in steps how to document the programmer's reference
>>> -and the demos respectively.
>>> +This style guide contains information on how to create documentation
>>> +for FEniCS using the Sphinx documentation tool. The first sections are
>>> +related to how the reST code should look. Then, a section on some
>>> +frequently used reST and Sphinx markup follows as a quick
>>> +reference. The last two sections are guides explaining in steps how to
>>> +document the programmer's reference and the demos respectively.
>>>
>>>  Code layout
>>>  -----------
>>> @@ -353,19 +353,20 @@
>>>  Use spaces instead of tabs for indentation.
>>>
>>>  Use 4 spaces per indentation level. This does not apply to C++ code
>>> -examples (DOLFIN) where the 2 space indentation rule apply.
>>> -See :ref:`C++ indentation <styleguides_cpp_coding_style_indentation>`.
>>> +examples (DOLFIN) where the 2 space indentation rule apply
>>> +(cf. :ref:`C++ indentation
>>> +<styleguides_cpp_coding_style_indentation>`).
>>>
>>> -The text width of normal text should not exceed 79 characters, but code example
>>> -tables and other cases where readability demands it this rule can be
>>> -disregarded.
>>> +The text width of normal text should not exceed 79 characters. This
>>> +rule can be disregarded if readability demands it, for instance for
>>> +code example tables.
>>>
>>>
>>>  Sections
>>>  --------
>>>
>>> -Section markers follow the convention from
>>> -`Python <http://docs.python.org/documenting/rest.html>`_:
>>> +Section markers follow the convention from the `Python Documentation
>>> +<http://docs.python.org/documenting/rest.html>`_:
>>>
>>>  * ``#`` with overline, for parts
>>>  * ``*`` with overline, for chapters
>>> @@ -379,8 +380,9 @@
>>>  Cross referencing
>>>  -----------------
>>>
>>> -Cross-references are created by placing labels at the location which you want
>>> -to refer to and then use ``:ref:\`label-name\``` to create the link. Example:
>>> +Cross-references are created by placing labels at the location you
>>> +want to refer to and then using ``:ref:\`label-name\``` to create the
>>> +link. Example:
>>>
>>>  .. code-block:: rest
>>>
>>> @@ -396,10 +398,10 @@
>>>  For this to work properly, the label names **must** be unique in the
>>>  entire documentation source.  To ensure this, the label names should
>>>  begin with the path to the file where the label is located relative to
>>> -the source directory. As an example the label for the C++ version of
>>> -the Poisson demo which is located at the top of the
>>> -``demos/cpp/pde/poisson/poisson.rst`` file should be given the name
>>> -``demos_cpp_pde_poisson`` while the label to this sub section is:
>>> +the source directory. For example, the label for the C++ version of
>>> +the Poisson demo, which is located at the top of the
>>> +``demos/cpp/pde/poisson/poisson.rst`` file, should be given the name
>>> +``demos_cpp_pde_poisson``, while the label to this sub section is:
>>>
>>>  .. code-block:: rest
>>>
>>> @@ -416,11 +418,12 @@
>>>  Code snippets
>>>  ^^^^^^^^^^^^^
>>>
>>> -The FEniCS documentation makes heavy use of code snippets to illustrate how the
>>> -interfaces work. Code snippets are created using the ``code-block`` directive
>>> -(see `showing code examples <http://sphinx.pocoo.org/markup/code.html>`_
>>> -for more details) which make it possible to show C++ and Python code
>>> -snippets in the the following way:
>>> +The FEniCS documentation makes heavy use of code snippets to
>>> +illustrate how the interfaces work. Code snippets are created using
>>> +the ``code-block`` directive (see `showing code examples
>>> +<http://sphinx.pocoo.org/markup/code.html>`_ for more details). This
>>> +makes it possible to show C++ and Python code snippets in the the
>>> +following way:
>>>
>>>  .. code-block:: rest
>>>
>>> @@ -457,12 +460,11 @@
>>>  Math
>>>  ^^^^
>>>
>>> -Writing FEniCS documentation often involves presenting mathematics especially
>>> -when documenting demos. We use the ``math`` role and directive to display
>>> -inline math and equations respectively (see
>>> -`math support in Sphinx <http://sphinx.pocoo.org/ext/math.html>`_ for more
>>> -details).
>>> -The input markup for math is LaTeX so the inline equation,
>>> +Writing FEniCS documentation often involves presenting mathematics,
>>> +especially when documenting demos. We use the ``math`` role and
>>> +directive to display inline math and equations respectively (see `math
>>> +support in Sphinx <http://sphinx.pocoo.org/ext/math.html>`_ for more
>>> +details).  The input markup for math is LaTeX, so the inline equation,
>>>  :math:`f(x) = x^2`, is typeset by
>>>
>>>  .. code-block:: rest
>>> @@ -475,7 +477,7 @@
>>>
>>>     a(v,u) = \int \nabla v \cdot \nabla u \; \rm{d}\Omega
>>>
>>> -is implemented as:
>>> +is typeset as
>>>
>>>  .. code-block:: rest
>>>
>>> @@ -492,7 +494,7 @@
>>>  Download files
>>>  ^^^^^^^^^^^^^^
>>>
>>> -To make a file available for download use the ``download`` role (see
>>> +To make a file available for download, use the ``download`` role (see
>>>  `inline markup <http://sphinx.pocoo.org/markup/inline.html>`_ for more
>>>  details) in the following way:
>>>
>>> @@ -503,8 +505,8 @@
>>>  Author comments
>>>  ^^^^^^^^^^^^^^^
>>>
>>> -Please refrain from using the keywords *note*, *todo* and *fixme* in comments
>>> -like:
>>> +Please refrain from using the keywords *note*, *todo* and *fixme* in
>>> +comments such as
>>>
>>>  .. code-block:: rest
>>>
>>> @@ -512,7 +514,7 @@
>>>     .. todo: Add more text and equations
>>>     .. fixme: The results look wrong, probably the boundary conditions
>>>
>>> -If you feel a comment is in its place use the ``note`` directive:
>>> +If you think a comment is required, use the ``note`` directive:
>>>
>>>  .. code-block:: rest
>>>
>>> @@ -520,8 +522,9 @@
>>>
>>>         Figure out how to present this in a better way
>>>
>>> -and ask on the fenics@xxxxxxxxxxxxxxxxxxx mailing list, so we can resolve the
>>> -issue as quickly as possible to keep the documentation in good shape.
>>> +and ask on the fenics@xxxxxxxxxxxxxxxxxxx mailing list in order for
>>> +the issue to be resolved as quickly as possible. This helps keeping
>>> +the documentation in good shape.
>>>
>>>  .. _styleguides_sphinx_documenting_interface:
>>>
>>> @@ -545,7 +548,7 @@
>>>  for the DOLFIN ``Mesh`` class and the ``closest_cell`` member function of this
>>>  class.
>>>
>>> -The ``Mesh`` class is defined in the file ``dofin_dir/dolfin/mesh/Mesh.h``.
>>> +The ``Mesh`` class is defined in the file ``dolfin_dir/dolfin/mesh/Mesh.h``.
>>>  We therefore start by adding the files:
>>>
>>>  * ``programmers-reference/cpp/mesh/Mesh.rst``
>>> @@ -566,16 +569,17 @@
>>>  General remarks
>>>  ^^^^^^^^^^^^^^^
>>>
>>> -To handle the documentation of two different languages in Sphinx we use
>>> -`Sphinx Domains <http://sphinx.pocoo.org/domains.html>`_ to distinguish between
>>> -classes and functions belonging to the C++ and Python interfaces.
>>> +To handle the documentation of two different languages in Sphinx, we
>>> +use `Sphinx Domains <http://sphinx.pocoo.org/domains.html>`_ to
>>> +distinguish between classes and functions belonging to the C++ and
>>> +Python interfaces.
>>>
>>> -Since Spinx does not allow sections in the markup for class/function
>>> -documentation we use *italics* (``*italics*``) and definition lists to group
>>> -information.
>>> -The idea is to keep the markup as simple as possible since the reST source for
>>> -the Python documentation of classes and functions will be used 'as is' in
>>> -the docstrings of the DOLFIN module.
>>> +As Sphinx does not allow sections in the markup for class/function
>>> +documentation, we use *italics* (``*italics*``) and definition lists
>>> +to group information.  The idea is to keep the markup as simple as
>>> +possible since the reST source for the Python documentation of classes
>>> +and functions will be used 'as is' in the docstrings of the DOLFIN
>>> +module.
>>>
>>>  Most information can be put in the three sections:
>>>
>>> @@ -608,23 +612,24 @@
>>>         integer
>>>             Some random integer.
>>>
>>> -* *Example*, a very small code snippet which shows how the class/function
>>> -  works. It does not necessarily have to be a stand-alone program.
>>> -
>>> -Links to demos which use the feature being documented should be put in a
>>> -``seealso`` directive.
>>> -
>>> -The member functions of a class should be sorted alphabetically for the
>>> -C++ version.
>>> -When using autodoc, Sphinx will sort the member functions automatically for the
>>> -Python module.
>>> +* *Example*, a very small code snippet that shows how the
>>> +  class/function works. It does not necessarily have to be a
>>> +  stand-alone program.
>>> +
>>> +Links to demos that use the feature being documented should be put in
>>> +a ``seealso`` directive.
>>> +
>>> +The member functions of a class should be sorted alphabetically for
>>> +the C++ version. When using autodoc, Sphinx will sort the member
>>> +functions automatically for the Python module.
>>>
>>>  C++ interface
>>>  ^^^^^^^^^^^^^^^^^
>>>
>>> -The code snippets presented in the following can be seen in their complete
>>> -form and context by clicking on ``Show Source`` link on the page containing
>>> -the C++ documentation for the :cpp:class:`Mesh` class.
>>> +The code snippets presented in the following can be seen in their
>>> +complete form and context by clicking on the ``Show Source`` link on
>>> +the page containing the C++ documentation for the :cpp:class:`Mesh`
>>> +class.
>>>
>>>  The C++ documentation for the ``Mesh`` class is added to the
>>>  ``programmers-reference/cpp/mesh/Mesh.rst`` file.
>>> @@ -632,8 +637,8 @@
>>>  Defining the class
>>>  """"""""""""""""""
>>>
>>> -The begining of the ``programmers-reference/cpp/mesh/Mesh.rst`` file looks
>>> -like this:
>>> +The beginning of the ``programmers-reference/cpp/mesh/Mesh.rst`` file
>>> +looks as follows:
>>>
>>>  .. code-block:: rest
>>>
>>> @@ -651,22 +656,22 @@
>>>  where only the first part of the ``Mesh`` class description has been included
>>>  for brevity.
>>>
>>> -We start with a section title ``Mesh.h`` since the ``Mesh.rst`` should contain
>>> -documentation for all classes and functions defined in ``Mesh.h`` and there
>>> -might be multiple classes defined.
>>> -The ``Mesh`` class is defined by the Sphinx directive ``cpp:class::`` followed
>>> -by the name of the class.
>>> -Since the ``Mesh`` class derives from the ``Variable`` class we list all parent
>>> -classes explicitly where the line ``:cpp:class:`Variable``` will create a link
>>> -to the C++ documentation of the class ``Variable``.
>>> +We start with a section title ``Mesh.h`` since the ``Mesh.rst`` should
>>> +contain documentation for all classes and functions defined in
>>> +``Mesh.h`` and there might be multiple classes defined.  The ``Mesh``
>>> +class is defined by the Sphinx directive ``cpp:class::`` followed by
>>> +the name of the class.  Since the ``Mesh`` class derives from the
>>> +``Variable`` class, we list all parent classes explicitly where the
>>> +line ``:cpp:class:`Variable``` will create a link to the C++
>>> +documentation of the class ``Variable``.
>>>
>>>  .. note::
>>>
>>>     In the future Sphinx might be clever enough to handle parent classes
>>>     automatically, but until then this is how we do it.
>>>
>>> -Then follows a description of the purpose of the ``Mesh`` class before th
>>> -documentation of the member functions.
>>> +Then follows a description of the purpose of the ``Mesh`` class before
>>> +the documentation of the member functions.
>>>
>>>  Constructors
>>>  """"""""""""
>>> @@ -697,13 +702,12 @@
>>>                 filename
>>>                     A string, name of file to load.
>>>
>>> -The funtions are defined in the class body such that they automatically have the
>>> -``Mesh`` namespace.
>>> -The signature of the functions (in this case the constructors
>>> -``Mesh(const Mesh& mesh)`` and ``Mesh(std::string filename)``) **must** be
>>> -identical to that found in the ``dolfin/mesh/Mesh.h`` file, otherwise
>>> -subsequent testing will report that the function is not documented
>>> -(or obsolete).
>>> +The functions are defined in the class body such that they
>>> +automatically have the ``Mesh`` namespace.  The signature of the
>>> +functions (in this case the constructors ``Mesh(const Mesh& mesh)``
>>> +and ``Mesh(std::string filename)``) **must** be identical to that
>>> +found in the ``dolfin/mesh/Mesh.h`` file, otherwise subsequent testing
>>> +will report that the function is not documented (or obsolete).
>>>
>>>  .. note::
>>>
>>> @@ -718,9 +722,9 @@
>>>  closest_cell function
>>>  """""""""""""""""""""
>>>
>>> -The documentation for the ``closest_cell`` function is added like documentation
>>> -for the constructors with additional information about the return value and an
>>> -example.
>>> +The documentation for the ``closest_cell`` function is added in the
>>> +same manner as the documentation for the constructors, but with
>>> +additional information about the return value and an example.
>>>
>>>  .. code-block:: rest
>>>
>>> @@ -748,8 +752,9 @@
>>>
>>>                 1
>>>
>>> -Again, the funtion is defined in the class body, and the signature of the
>>> -function is identical to that found in the ``dolfin/mesh/Mesh.h`` file.
>>> +Again, the function is defined in the class body, and the signature of
>>> +the function is identical to that found in the ``dolfin/mesh/Mesh.h``
>>> +file.
>>>
>>>  .. note::
>>>
>>> @@ -762,17 +767,18 @@
>>>  Python interface
>>>  ^^^^^^^^^^^^^^^^
>>>
>>> -The code snippets presented in the following can be seen in their complete
>>> -form and context by clicking on ``Show Source`` link on the page containing
>>> -the Python documentation for the :py:class:`dolfin.cpp.Mesh` class and in the
>>> -:download:`programmers-reference/python/docstrings/dolfin/cpp.py` file which
>>> -contains the actual documentation for the Python ``Mesh`` class.
>>> +The code snippets presented in the following can be seen in their
>>> +complete form and context by clicking on the ``Show Source`` link on
>>> +the page containing the Python documentation for the
>>> +:py:class:`dolfin.cpp.Mesh` class and in the
>>> +:download:`programmers-reference/python/docstrings/dolfin/cpp.py` file
>>> +which contains the actual documentation for the Python ``Mesh`` class.
>>>
>>>  The Python ``Mesh`` class is defined in the :py:mod:`dolfin.cpp`
>>> -module which is automatically generated by Swig from the DOLFIN C++
>>> -implementation.  In order to have the documentation for the Python
>>> -interface available from within the Python interpreter we will put the
>>> -docstrings for the ``Mesh`` class in the appropriate file of the
>>> +module. This module is automatically generated by Swig from the DOLFIN
>>> +C++ implementation.  In order to have the documentation for the Python
>>> +interface available from within the Python interpreter, we will put
>>> +the docstrings for the ``Mesh`` class in the appropriate file of the
>>>  pseudo module containing the dolfin docstrings namely
>>>  ``programmers-reference/python/docstrings/dolfin/cpp.py``.
>>>
>>> @@ -791,10 +797,10 @@
>>>         [snip]
>>>         """
>>>
>>> -where only the first part of the ``Mesh`` class description has been included
>>> -for brevity.
>>> -Since the docstrings module requires correct Python syntax the parent class
>>> -``Variable`` must of course be defined also.
>>> +where only the first part of the ``Mesh`` class description has been
>>> +included for brevity.  Since the docstrings module requires correct
>>> +Python syntax the parent class ``Variable`` must of course be defined
>>> +also.
>>>
>>>  Construtors
>>>  """""""""""
>>> @@ -832,13 +838,13 @@
>>>                       A string, name of file to load.
>>>             """
>>>
>>> -Since the constructor is overloaded we use the argument list ``(self, *args)``
>>> -in the function definition and the ``**Overloaded versions**`` section to
>>> -document the overloaded versions in a standard list using ``*``.
>>> -For each constructor we define the argument list using **bold face**. The ``\``
>>> -is needed to avoid adding space between the function name (``Mesh``) and the
>>> -argument list.
>>> -Each constructor is then documented as any other function.
>>> +Since the constructor is overloaded, we use the argument list ``(self,
>>> +*args)`` in the function definition and the ``**Overloaded
>>> +versions**`` section to document the overloaded versions in a standard
>>> +list using ``*``.  For each constructor we define the argument list
>>> +using **bold face**. The ``\`` is needed to avoid adding space between
>>> +the function name (``Mesh``) and the argument list.  Each constructor
>>> +is then documented as any other function.
>>>
>>>  .. note::
>>>
>>> @@ -850,9 +856,9 @@
>>>  closest_cell function
>>>  """""""""""""""""""""
>>>
>>> -The documentation for the ``closest_cell`` function is added like documentation
>>> -for the constructors with additional information about the return value and an
>>> -example.
>>> +The documentation for the ``closest_cell`` function is added in the
>>> +same manner as the documentation for the constructors, but with
>>> +additional information about the return value and an example.
>>>
>>>  .. code-block:: rest
>>>
>>> @@ -908,13 +914,13 @@
>>>  Appendices
>>>  ^^^^^^^^^^
>>>
>>> -Documentation for the FFC, UFC and UFL components of FEniCS are located in
>>> -the :ref:`appendix <programmers_reference_appendices_index>`.
>>> -The structure of the documentation of a given module depends on the file/class
>>> -layout of the module and the content should be extracted from the docstrings
>>> -as is done for the Python interface to DOLFIN.
>>> -The layout of the docstrings should follow the same rules as outlined in the
>>> -above sections.
>>> +Documentation for the FFC, UFC and UFL components of FEniCS is located
>>> +in the :ref:`appendix <programmers_reference_appendices_index>`.  The
>>> +structure of the documentation of a given module depends on the
>>> +file/class layout of the module and the content should be extracted
>>> +from the docstrings as is done for the Python interface to DOLFIN.
>>> +The layout of the docstrings should follow the same rules as outlined
>>> +in the above sections.
>>>
>>>  Testing the documentation
>>>  ^^^^^^^^^^^^^^^^^^^^^^^^^
>>> @@ -941,16 +947,17 @@
>>>  -----------------
>>>
>>>  This short guide explains the procedure for documenting a FEniCS demo.
>>> -As an example we will demonstrate the steps involved to create documentation
>>> -for the :ref:`Poisson (C++) <demos_cpp_pde_poisson>` and
>>> +As an example, we will demonstrate the steps involved to create
>>> +documentation for the :ref:`Poisson (C++) <demos_cpp_pde_poisson>` and
>>>  :ref:`Poisson (Python) <demos_python_pde_poisson>` demos.
>>>
>>>  Files
>>>  ^^^^^
>>>
>>> -The documentation is located in the ``source/demos`` directory which contains
>>> -the directories ``common``, ``cpp`` and ``python``.
>>> -First you must figure out which category your demo belongs to:
>>> +The demo documentation is located in the ``source/demos``
>>> +directory. This directory contains the sub-directories ``common``,
>>> +``cpp`` and ``python``.  First you must figure out which category your
>>> +demo belongs to:
>>>
>>>  1. adaptivity
>>>  2. fem
>>> @@ -967,61 +974,73 @@
>>>
>>>     This might change in case we decide to reorganise the demos!
>>>
>>> -In our case the Poisson demo is a partial differential equation (PDE), so
>>> -we should add the following files:
>>> +The Poisson demo mainly demonstrates how to solve a certain partial
>>> +differential equation (PDE), so we should add the following files:
>>>
>>>  ``demos/common/pde/poisson/poisson.txt``
>>> -    put common information is this file and include in the C++ and
>>> -    Python versions (see :ref:`styleguides_sphinx_common_information`).
>>> +    Common information should be placed in this file, and the file
>>> +    should then be included in the C++ and Python versions (see
>>> +    :ref:`styleguides_sphinx_common_information`).
>>>
>>>  ``demos/cpp/pde/poisson/poisson.rst``
>>> -    this file contains the reST source file with the documentation which is
>>> +    This file contains the reST source file with the documentation that is
>>>     specific to the C++ version of the Poisson demo.
>>>
>>>  ``demos/cpp/pde/poisson/main.cpp``
>>> -    this file contains the entire source code for the solver and must be made
>>> +    This file contains the entire source code for the solver and must be made
>>>     available for :ref:`download <styleguides_sphinx_download_files>`.
>>>
>>>  ``demos/cpp/pde/poisson/Poisson.ufl``
>>> -    this file contains the form file and must be made available for
>>> +    This file contains the form file and must be made available for
>>>     :ref:`download <styleguides_sphinx_download_files>`.
>>> -    If your demo contains multiple form files they too must be added.
>>> +    If your demo contains multiple form files, all of these must be added.
>>> +
>>>
>>>  ``demos/cpp/pde/poisson/SConstruct``
>>> -    this file is necessary to compile the demo against DOLFIN, and must be
>>> +    This file is necessary to compile the demo against DOLFIN and must be
>>>     made available for :ref:`download <styleguides_sphinx_download_files>`.
>>>
>>> +.. warning::
>>> +
>>> +    The information about SConstruct must be updated cf. transition to cmake.
>>> +
>>> +
>>>  ``demos/python/pde/poisson/poisson.rst``
>>> -    this file contains the reST source file with the documentation which is
>>> -    specific to the Python version of the Poisson demo.
>>> +    This file contains the reST source file with the documentation
>>> +    that is specific to the Python version of the Poisson demo.
>>>
>>>  ``demos/python/pde/poisson/demo.py``
>>> -    this file contains the entire solver writte in PyDOLFIN, and must be made
>>> -    available for :ref:`download <styleguides_sphinx_download_files>`.
>>> +    This file contains the entire solver written in PyDOLFIN, and must
>>> +    be made available for :ref:`download
>>> +    <styleguides_sphinx_download_files>`.
>>>
>>>  Finally, add the demo to the index files ``demos/python/pde/index`` and
>>>  ``demos/cpp/pde/index`` by adding ``poisson/poisson`` to the ``toctree`` to
>>>  complete the setup of files.
>>>
>>> -The source code files should of course be able to run with the versions of
>>> -FEniCS software e.g., DOLFIN, FFC and UFL, which is covered by the current
>>> -documentation.
>>> +The source code files should of course compile and run with the
>>> +versions of FEniCS software covered by the current documentation.
>>> +
>>> +.. note::
>>> +
>>> +    Will the fact that the demos in the documentation compile and run
>>> +    be tested automatically by the buildbot?
>>> +
>>>
>>>  .. _styleguides_sphinx_common_information:
>>>
>>>  Common information
>>>  ^^^^^^^^^^^^^^^^^^
>>>
>>> -The demo has to be available in a C++ and a Python version.
>>> -However, the summary (describing what features are demonstrated) along with the
>>> -problem and method description are typically identical for both versions.
>>> -It is therefore desirable to put this information in a common source file to
>>> -avoid code duplication.
>>> -In this case this code is put in the file
>>> -``demos/common/pde/poisson/poisson.txt`` which is then included in the two files
>>> -``demos/cpp/pde/poisson/poisson.rst`` and
>>> -``demos/python/pde/poisson/poisson.rst`` using the ``include`` directive with
>>> -the relative path to the file:
>>> +Each demo should be available in both a C++ and a Python version.
>>> +However, the summary (describing what features are demonstrated) along
>>> +with the problem and method description are typically identical for
>>> +both versions.  It is therefore desirable to put this information in a
>>> +common source file to avoid code duplication.  This common code is
>>> +placed in the file ``demos/common/pde/poisson/poisson.txt``, which is
>>> +then included in the two files ``demos/cpp/pde/poisson/poisson.rst``
>>> +and ``demos/python/pde/poisson/poisson.rst`` using the ``include``
>>> +directive with the relative path to the file:
>>>
>>>  .. code-block:: rest
>>>
>>> @@ -1030,9 +1049,9 @@
>>>  C++ and Python specific contents
>>>  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>>
>>> -Each step of the solution procedure of a demo should be explained. Often this
>>> -is achieved by including :ref:`styleguides_sphinx_code_snippets` which of
>>> -course must be given in the correct syntax depending on the demo version.
>>> +Each step of the solution procedure of a demo should be
>>> +explained. This can often be achieved by including
>>> +:ref:`styleguides_sphinx_code_snippets`.
>>>
>>>  .. warning::
>>>
>>> @@ -1041,9 +1060,9 @@
>>>     compiled and tested against DOLFIN and if anything is broken the demos
>>>     needs to be updated.
>>>
>>> -    Running the script ``test/verify_code_snippets.py`` in the top level directory
>>> -    will then locate all code snippets that needs to be updated to the new
>>> -    syntax.
>>> +    Running the script ``test/verify_code_snippets.py`` in the top
>>> +    level directory will then locate all code snippets that needs to
>>> +    be updated to the new syntax.
>>>
>>>  As an example, the definition of the Dirichlet boundary is:
>>>
>>> @@ -1069,16 +1088,17 @@
>>>  Additional information
>>>  ^^^^^^^^^^^^^^^^^^^^^^
>>>
>>> -Use the ``note`` and ``warning`` directives to highligt important information.
>>> -The ``seealso`` directive should be used when pointing to alternative
>>> -solutions or functions in the :ref:`programmers_reference_index`.
>>> +Use the ``note`` and ``warning`` directives to highlight important
>>> +information.  The ``seealso`` directive should be used when pointing
>>> +to alternative solutions or functions in the
>>> +:ref:`programmers_reference_index`.
>>>
>>>  Keywords should be added to the index, using the ``index`` directive to make
>>>  the documentation easier to navigate through.
>>>
>>>  See `the Sphinx documentation
>>> -<http://sphinx.pocoo.org/markup/para.html#index-generating-markup>`_ on how to
>>> -use the above directives.
>>> +<http://sphinx.pocoo.org/markup/para.html#index-generating-markup>`_
>>> +for how to use the above directives.
>>>
>>>  Testing the documentation
>>>  ^^^^^^^^^^^^^^^^^^^^^^^^^
>>>
>>>
>>>
>>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~fenics
>> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~fenics
>> More help   : https://help.launchpad.net/ListHelp
>>
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp
>