fenics team mailing list archive

[Marie Rognes <meg@xxxxxxxxx>]

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


>>  - 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".


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