Add script to call sphinx-apidoc and other doc changes.

README

@@ -26,10 +26,10 @@ Contributors:
 
 UFL is described in the paper:
 
-Alnæs, M. S., Logg A., Ølgaard, K. B., Rognes, M. E. and Wells, G. N. (2014).
-Unified Form Language: A domain-specific language for weak formulations of
-partial differential equations.
-*ACM Transactions on Mathematical Software* 40(2), Article 9, 37 pages.
+Alnæs, M. S., Logg A., Ølgaard, K. B., Rognes, M. E. and Wells,
+G. N. (2014).  Unified Form Language: A domain-specific language for
+weak formulations of partial differential equations.  *ACM
+Transactions on Mathematical Software* 40(2), Article 9, 37 pages.
 <http://dx.doi.org/doi:10.1145/2566630>,
 <http://arxiv.org/abs/1211.4047>
 
@@ -59,15 +59,12 @@ Directories
 
 - doc/
 
-  The UFL manual resides here.
+  The UFL documentation resides here.
 
 - test/
 
-  Unit tests for the UFL implementation. Run all tests by typing "python test.py" inside the test/ directory.
-
-- sandbox/
-
-  A place for experimental scripts and other unofficial code.
+  Unit tests for the UFL implementation. Run all tests by typing
+  "python test.py" inside the test/ directory.
 
 
 Utilities
@@ -85,11 +82,13 @@ after installation.
 About the Python modules
 ========================
 
-The global namespace of the module ufl contains the entire UFL language::
+The global namespace of the module ufl contains the entire UFL
+language::
 
   from ufl import *
 
-Form compilers may want to import additional implementation details like::
+Form compilers may want to import additional implementation details
+like::
 
   from ufl.classes import *
 

doc/sphinx/generate-apidoc

@@ -0,0 +1,33 @@
+# Copyright (C) 2015 Garth N. Wells
+#
+# This file is part of UFL.
+#
+# UFL is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# UFL is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with UFL. If not, see <http://www.gnu.org/licenses/>.
+
+# This script calls sphinx-apidoc to generate files ready for autodoc
+#
+# Run from the top level UFL directory:
+#
+#    ./scripts/makedoc
+#
+
+echo ""
+echo "--- Generating UFL autodoc RST files"
+echo ""
+
+SPHINX_DIR=.
+SPHINX_SOURCE_DIR=$SPHINX_DIR/source
+
+# Generate .rst files ready for autodoc
+sphinx-apidoc -f -d 1 -o $SPHINX_SOURCE_DIR/api-doc ../../ufl

doc/sphinx/source/api-doc/modules.rst

@@ -2,6 +2,6 @@ ufl
 ===
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 1
 
    ufl

doc/sphinx/source/index.rst

@@ -1,30 +1,26 @@
-.. Unified Form Language (UFL) documentation master file, created by
-   sphinx-quickstart on Tue Nov  3 11:05:14 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 .. title:: Unified Form Language
 
-Unified Form Language (UFL) documentation
-=========================================
+Unified Form Language (UFL)
+===========================
 
 This is the documentation for the Unified Form Language from the
-FEniCS Project (http://fenicsproject.org).
-
-
-The Unified Form Language (UFL) is a domain specific language for
-declaration of finite element discretizations of variational
-forms. More precisely, it defines a flexible interface for choosing
-finite element spaces and defining expressions for weak forms in a
-notation close to mathematical notation. UFL is described in the paper
+FEniCS Project (http://fenicsproject.org). The Unified Form Language
+(UFL) is a domain specific language for declaration of finite element
+discretizations of variational forms. More precisely, it defines a
+flexible interface for choosing finite element spaces and defining
+expressions for weak forms in a notation close to mathematical
+notation. UFL is described in the paper
 
 Alnæs, M. S., Logg A., Ølgaard, K. B., Rognes, M. E. and
 Wells, G. N. (2014). Unified Form Language: A domain-specific language
-for weak formulations of partial differential equations. ACM
-Transactions on Mathematical Software 40(2), Article 9, 37
+for weak formulations of partial differential equations. *ACM
+Transactions on Mathematical Software* 40(2), Article 9, 37
 pages. [http://dx.doi.org/doi:10.1145/2566630>]
 [http://arxiv.org/abs/1211.4047]
 
+UFL is most commonly used as the input language for the FEniCS Form
+Compiler (FFC) and in combination with the problem solving environment
+DOLFIN.
 
 
 Installation
@@ -39,19 +35,6 @@ To install UFL::
     python setup.py install
 
 
-
-Documentation
--------------
-
-.. toctree::
-   :maxdepth: 2
-
-* :ref:`modindex`
-* :ref:`genindex`
-* :ref:`search`
-
-
-
 Help and support
 ----------------
 
@@ -60,7 +43,6 @@ Send help requests and questions to fenics-support@fenicsproject.org.
 Send feature requests and questions to fenics@fenicsproject.org
 
 
-
 Development and reporting bugs
 ------------------------------
 
@@ -70,3 +52,18 @@ questions and to make feature requests, use fenics@fenicsproject.org.
 
 Bugs can be registered at
 https://bitbucket.org/fenics-project/ufl/issues.
+
+
+Documentation
+-------------
+
+.. toctree::
+   :titlesonly:
+
+   api-doc/ufl
+   releases
+
+
+* :ref:`modindex`
+* :ref:`genindex`
+* :ref:`search`

doc/sphinx/source/releases.rst

@@ -0,0 +1,7 @@
+Release notes
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   releases/next

doc/sphinx/source/releases/next.rst

@@ -0,0 +1,2 @@
+Changes in the next release of UFL
+==================================