fenics team mailing list archive

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

On 26 August 2010 12:04,  <noreply@xxxxxxxxxxxxx> wrote:
> ------------------------------------------------------------
> revno: 64
> committer: Anders Logg <logg@xxxxxxxxx>
> branch nick: fenics-doc
> timestamp: Thu 2010-08-26 12:01:54 +0200
> message:
>  Work on programmer's reference.
> modified:
>  source/programmers-reference/index.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/programmers-reference/index.rst'
> --- source/programmers-reference/index.rst      2010-08-25 16:14:51 +0000
> +++ source/programmers-reference/index.rst      2010-08-26 10:01:54 +0000
> @@ -6,46 +6,44 @@
>  FEniCS Programmer's Reference
>  #############################
>
> -From the Launchpad `blueprint
> -<https://blueprints.launchpad.net/fenics-doc/+spec/user-manual>`_:
> -
> -* The FEniCS User Manual should be hand-written in reST and converted to HTML
> -  and PDF using Sphinx.
> -
> -* Relevant parts should also be available as docstrings in the Python
> -  interface. This should be possible to fix with some clever scripting
> -  (assigning to __doc__).
> -
> -* It should come in two different flavors, C++ and Python. As much as possible,
> -  material should be reused between the two.
> -
> -* It should replace the current user manuals for DOLFIN, FFC, UFL and UFC.
> -
> -* Emphasis should be on documenting the DOLFIN user interface. Details for FFC,
> -  UFL and UFC should be placed in Appendix.
> -
> -* It should include numerous small examples (code snippets) that illustrate
> -  each function.
> -
> -* It should contain a HOWTO chapter that answers questions like how do I set
> -  Neumann boundary conditions, how do I compute norms, how do I compute errors
> -  etc.
> -
> -Contents:
> -
> -.. toctree::
> -    :maxdepth: 1
> -
> -    cpp/index
> -    python/index
> -    appendices/index
> -
> -The programmer's references are also available in PDF format, see
> -:download:`C++ version<../../build/latex/cpp_programmers_reference.pdf>` or
> -:download:`Python version<../../build/latex/python_programmers_reference.pdf>`.

So we no longer want to make the programmer's reference available as PDF?
I personally don't think that we need it.

> -.. note::
> -
> -    Build PDFs for FFC, UFC and UFL manuals and link to those too.

I assume we'll add links to these pages as part of an appendix (which
was the original idea) once they have some contents?

> -
> +The FEniCS Programmer's Reference documents the details of the FEniCS
> +user interface. The FEniCS user interface is available in two
> +different flavors: both as a Python module and as a C++ library.
> +
> +Both interfaces are implemented as part of `DOLFIN
> +<http://www.fenics.org/dolfin>`_.
> +
> +Python interface
> +================
> +
> +To use FEniCS from Python, users need to import functionality from the
> +DOLFIN Python module. In the simplest caset, one includes all
> +functionality from the Python module named ``dolfin``:
> +
> +.. code-block:: python
> +
> +    from dolfin import *
> +
> +For documentation of the DOLFIN Python module, see the `Python Programmer's Reference <python/index.html>`_.

Someone needs to read the Sphinx style guide on cross-referencing :)

Kristian

> +C++ interface
> +=============
> +
> +To use FEniCS from C++, users need to include one or more header files
> +from the DOLFIN C++ library. In the simplest case, one includes the
> +header file ``dolfin.h``, which in turn includes all other DOLFIN
> +header files:
> +
> +.. code-block:: c++
> +
> +    #include <dolfin.h>
> +
> +    using namespace dolfin;
> +
> +    int main()
> +    {
> +
> +      return 0;
> +    }
> +
> +For documentation of the DOLFIN C++ library, see the `C++ Programmer's Reference <cpp/index.html>`_.
>
> === modified file 'source/styleguides.rst'
> --- source/styleguides.rst      2010-08-26 09:33:01 +0000
> +++ source/styleguides.rst      2010-08-26 10:01:54 +0000
> @@ -327,8 +327,8 @@
>
>  .. _styleguides_sphinx_coding_style:
>
> -Sphinx coding style for FEniCS documentation
> -============================================
> +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
>
>
>