On 30 August 2010 14:41, Marie Rognes <[email protected]> wrote: > On 30. aug. 2010 14:34, Kristian Ølgaard wrote: >> ---------- Forwarded message ---------- >> From: Kristian Ølgaard <[email protected]> >> 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: [email protected] >> >> >> On 30 August 2010 14:02, <[email protected]> wrote: >> >>> ------------------------------------------------------------ >>> revno: 113 >>> committer: Marie E. Rognes <[email protected]> >>> 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 [email protected] mailing list, so we can resolve >>> the >>> -issue as quickly as possible to keep the documentation in good shape. >>> +and ask on the [email protected] 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 : [email protected] >> Unsubscribe : https://launchpad.net/~fenics >> More help : https://help.launchpad.net/ListHelp >> > > > _______________________________________________ > Mailing list: https://launchpad.net/~fenics > Post to : [email protected] > Unsubscribe : https://launchpad.net/~fenics > More help : https://help.launchpad.net/ListHelp > _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
