YAML format documentation

README.md

@@ -10,8 +10,10 @@ site is built using the [Nikola](https://getnikola.com) static site generator.
 3. Clone the Cantera Jupyter examples: `git clone https://github.com/Cantera/cantera-jupyter.git`
 4. Clone the Cantera website source: `git clone https://github.com/Cantera/cantera-website.git`
 5. Enter the website repo: `cd cantera-website`
-6. Inside the website repo, install the required packages: `pip install -r requirements.txt`
-7. Build the website and open in browser: `nikola auto -b`
+6. Copy the current development documentation: `curl -O https://cantera.org/documentation/dev/dev-docs.tar.bz2`
+7. Extract the dev docs: `tar jxf dev-docs.tar.bz2 --strip-components=1 -C api-docs/dev`
+8. Inside the website repo, install the required packages: `pip install -r requirements.txt`
+9. Build the website and open in browser: `nikola auto -b`
 
 ## To add a language of examples
 

api-docs/dev/.gitignore

@@ -0,0 +1,4 @@
+# Ignore everything in this directory
+*
+# Except this file
+!.gitignore

conf.py

@@ -272,6 +272,7 @@
 
 # This is the "production" version of this dictionary
 DOCS_FOLDERS = {
+    "api-docs/dev": "documentation/dev",
     "api-docs/docs-2.0": "documentation/docs-2.0",
     "api-docs/docs-2.1": "documentation/docs-2.1",
     "api-docs/docs-2.2": "documentation/docs-2.2",

pages/community.rst

@@ -65,11 +65,11 @@ For installation/compilation problems, please provide:
        scons build >buildlog.txt 2>&1
 
 * The exact version of Cantera you are trying to compile, and how it was
-  obtained (i.e., downloaded source tarball or the specific Git commit).
+  obtained (for example, downloaded source tarball or the specific Git commit).
 * Your operating system, compiler versions, and the versions of any other
   relevant software.
 
-For application problems (i.e., not related to installation or compilation),
+For application problems (that is, not related to installation or compilation),
 please:
 
 * Provide a minimal, complete, and verifiable example that demonstrates

pages/compiling/config-options-dev.rst

@@ -93,7 +93,7 @@ Options List
 * ``python_package``: [ ``y`` | ``n`` | ``full`` | ``minimal`` | ``none`` | ``default`` ]
     If you plan to work in Python, then you need the ``full`` Cantera Python
     package. If, on the other hand, you will only use Cantera from some
-    other language (e.g. MATLAB or Fortran 90/95) and only need Python
+    other language (for example, MATLAB or Fortran 90/95) and only need Python
     to process CTI files, then you only need a ``minimal`` subset of the
     package and Cython and NumPy are not necessary. The ``none`` option
     doesn't install any components of the Python interface. The default
@@ -231,9 +231,9 @@ Options List
 * ``system_eigen``: [ ``default`` | ``y`` | ``n`` ]
     Select whether to use Eigen from a system installation (``y``), from a
     Git submodule (``n``), or to decide automatically (``default``). If
-    Eigen is not installed directly into a system include directory,
-    e.g. it is installed in ``/opt/include/eigen3/Eigen``, then you will
-    need to add ``/opt/include/eigen3`` to the ``extra_inc_dirs`` option.
+    Eigen is not installed directly into a system include directory --
+    for example, if it is installed in ``/opt/include/eigen3/Eigen`` -- then you
+    will need to add ``/opt/include/eigen3`` to the ``extra_inc_dirs`` option.
 
     - default: ``'default'``
 
@@ -262,15 +262,15 @@ Options List
     The directory where the SUNDIALS header files are installed. This
     should be the directory that contains the ``cvodes``, ``nvector``, etc.
     subdirectories. Not needed if the headers are installed in a
-    standard location, e.g., ``/usr/include``.
+    standard location such as ``/usr/include``.
 
     - default: ``''``
 
 .. _sundials-libdir-dev:
 
 * ``sundials_libdir``: [ ``/path/to/sundials_libdir`` ]
     The directory where the SUNDIALS static libraries are installed. Not
-    needed if the libraries are installed in a standard location, e.g.,
+    needed if the libraries are installed in a standard location such as
     ``/usr/lib``.
 
     - default: ``''``
@@ -279,10 +279,10 @@ Options List
 
 * ``blas_lapack_libs``: [ ``string`` ]
     Cantera can use BLAS and LAPACK libraries available on your system
-    if you have optimized versions available (e.g., Intel MKL).
+    if you have optimized versions available (for example, Intel MKL).
     Otherwise, Cantera will use Eigen for linear algebra support. To use
     BLAS and LAPACK, set ``blas_lapack_libs`` to the the list of libraries
-    that should be passed to the linker, separated by commas, e.g.,
+    that should be passed to the linker, separated by commas -- for example,
     ``"lapack,blas"`` or ``"lapack,f77blas,cblas,atlas"``.
 
     - default: ``''``
@@ -291,7 +291,7 @@ Options List
 
 * ``blas_lapack_dir``: [ ``/path/to/blas_lapack_dir`` ]
     Directory containing the libraries specified by ``blas_lapack_libs``. Not
-    needed if the libraries are installed in a standard location, e.g.
+    needed if the libraries are installed in a standard location such as
     ``/usr/lib``.
 
     - default: ``''``
@@ -301,7 +301,7 @@ Options List
 * ``lapack_names``: [ ``lower`` | ``upper`` ]
     Set depending on whether the procedure names in the specified
     libraries are lowercase or uppercase. If you don't know, run ``nm`` on
-    the library file (e.g., ``nm libblas.a``).
+    the library file (for example, ``nm libblas.a``).
 
     - default: ``'lower'``
 
@@ -347,7 +347,7 @@ Options List
 
 * ``env_vars``: [ ``string`` ]
     Environment variables to propagate through to SCons. Either the
-    string ``all`` or a comma separated list of variable names, e.g.
+    string ``all`` or a comma separated list of variable names such as
     ``LD_LIBRARY_PATH,HOME``.
 
     - default: ``'LD_LIBRARY_PATH,PYTHONPATH'``
@@ -363,7 +363,7 @@ Options List
 
 * ``cxx_flags``: [ ``string`` ]
     Compiler flags passed to the C++ compiler only. Separate multiple
-    options with spaces, e.g., ``cxx_flags='-g -Wextra -O3 --std=c++11'``
+    options with spaces -- for example, ``cxx_flags='-g -Wextra -O3 --std=c++11'``
 
     - default: ``''``
 
@@ -449,7 +449,7 @@ Options List
 * ``warning_flags``: [ ``string`` ]
     Additional compiler flags passed to the C/C++ compiler to enable
     extra warnings. Used only when compiling source code that is part of
-    Cantera (e.g. excluding code in the 'ext' directory).
+    Cantera (for example, excluding code in the 'ext' directory).
 
     - default: ``''``
 
@@ -473,15 +473,15 @@ Options List
 
 * ``boost_inc_dir``: [ ``/path/to/boost_inc_dir`` ]
     Location of the Boost header files. Not needed if the headers are
-    installed in a standard location, e.g. ``/usr/include``.
+    installed in a standard location such as ``/usr/include``.
 
     - default: ``''``
 
 .. _stage-dir-dev:
 
 * ``stage_dir``: [ ``/path/to/stage_dir`` ]
     Directory relative to the Cantera source directory to be used as a
-    staging area for building e.g., a Debian package. If specified,
+    staging area for building, for example, a Debian package. If specified,
     ``scons install`` will install files to ``stage_dir/prefix/...``.
 
     - default: ``''``
@@ -496,7 +496,7 @@ Options List
 .. _gtest-flags-dev:
 
 * ``gtest_flags``: [ ``string`` ]
-    Additional options passed to each GTest test suite, e.g.
+    Additional options passed to each GTest test suite, for example
     `--gtest_filter=*pattern*`. Separate multiple options with spaces.
 
 .. _renamed-shared-libraries-dev:
@@ -515,7 +515,7 @@ Options List
 
 * ``versioned_shared_library``: [ ``yes`` | ``no`` ]
     If enabled, create a versioned shared library, with symlinks to the
-    more generic library name, e.g. ``libcantera_shared.so.2.4.0`` as the
+    more generic library name, for example ``libcantera_shared.so.2.4.0`` as the
     actual library and ``libcantera_shared.so`` and ``libcantera_shared.so.2``
     as symlinks.
 
@@ -525,7 +525,7 @@ Options List
 
 * ``layout``: [ ``standard`` | ``compact`` | ``debian`` ]
     The layout of the directory structure. 'standard' installs files to
-    several subdirectories under 'prefix', e.g. $prefix/bin,
+    several subdirectories under 'prefix', for example, $prefix/bin,
     $prefix/include/cantera, $prefix/lib. This layout is best used in
     conjunction with 'prefix'='/usr/local'. 'compact' puts all installed
     files in the subdirectory defined by 'prefix'. This layout is best

pages/compiling/config-options.rst

@@ -93,7 +93,7 @@ Options List
 * ``python_package``: [ ``y`` | ``n`` | ``full`` | ``minimal`` | ``none`` | ``default`` ]
     If you plan to work in Python, then you need the ``full`` Cantera Python
     package. If, on the other hand, you will only use Cantera from some
-    other language (e.g. MATLAB or Fortran 90/95) and only need Python
+    other language (for example, MATLAB or Fortran 90/95) and only need Python
     to process CTI files, then you only need a ``minimal`` subset of the
     package and Cython and NumPy are not necessary. The ``none`` option
     doesn't install any components of the Python interface. The default
@@ -297,8 +297,8 @@ Options List
 * ``system_eigen``: [ ``default`` | ``y`` | ``n`` ]
     Select whether to use Eigen from a system installation (``y``), from a
     Git submodule (``n``), or to decide automatically (``default``). If
-    Eigen is not installed directly into a system include directory,
-    e.g. it is installed in ``/opt/include/eigen3/Eigen``, then you will
+    Eigen is not installed directly into a system include directory --
+    for example, it is installed in ``/opt/include/eigen3/Eigen``, then you will
     need to add ``/opt/include/eigen3`` to the ``extra_inc_dirs`` option.
 
     - default: ``'default'``
@@ -328,15 +328,15 @@ Options List
     The directory where the SUNDIALS header files are installed. This
     should be the directory that contains the ``cvodes``, ``nvector``, etc.
     subdirectories. Not needed if the headers are installed in a
-    standard location, e.g., ``/usr/include``.
+    standard location such as ``/usr/include``.
 
     - default: ``''``
 
 .. _sundials-libdir:
 
 * ``sundials_libdir``: [ ``/path/to/sundials_libdir`` ]
     The directory where the SUNDIALS static libraries are installed. Not
-    needed if the libraries are installed in a standard location, e.g.,
+    needed if the libraries are installed in a standard location such as
     ``/usr/lib``.
 
     - default: ``''``
@@ -345,10 +345,10 @@ Options List
 
 * ``blas_lapack_libs``: [ ``string`` ]
     Cantera can use BLAS and LAPACK libraries available on your system
-    if you have optimized versions available (e.g., Intel MKL).
+    if you have optimized versions available (for example, Intel MKL).
     Otherwise, Cantera will use Eigen for linear algebra support. To use
     BLAS and LAPACK, set ``blas_lapack_libs`` to the the list of libraries
-    that should be passed to the linker, separated by commas, e.g.,
+    that should be passed to the linker, separated by commas -- for example,
     ``"lapack,blas"`` or ``"lapack,f77blas,cblas,atlas"``.
 
     - default: ``''``
@@ -357,7 +357,7 @@ Options List
 
 * ``blas_lapack_dir``: [ ``/path/to/blas_lapack_dir`` ]
     Directory containing the libraries specified by ``blas_lapack_libs``. Not
-    needed if the libraries are installed in a standard location, e.g.
+    needed if the libraries are installed in a standard location such as
     ``/usr/lib``.
 
     - default: ``''``
@@ -367,7 +367,7 @@ Options List
 * ``lapack_names``: [ ``lower`` | ``upper`` ]
     Set depending on whether the procedure names in the specified
     libraries are lowercase or uppercase. If you don't know, run ``nm`` on
-    the library file (e.g., ``nm libblas.a``).
+    the library file (for example, ``nm libblas.a``).
 
     - default: ``'lower'``
 
@@ -413,7 +413,7 @@ Options List
 
 * ``env_vars``: [ ``string`` ]
     Environment variables to propagate through to SCons. Either the
-    string ``all`` or a comma separated list of variable names, e.g.
+    string ``all`` or a comma separated list of variable names such as
     ``LD_LIBRARY_PATH,HOME``.
 
     - default: ``'LD_LIBRARY_PATH,PYTHONPATH'``
@@ -429,7 +429,7 @@ Options List
 
 * ``cxx_flags``: [ ``string`` ]
     Compiler flags passed to the C++ compiler only. Separate multiple
-    options with spaces, e.g., ``cxx_flags='-g -Wextra -O3 --std=c++11'``
+    options with spaces, such as ``cxx_flags='-g -Wextra -O3 --std=c++11'``
 
     - default: ``''``
 
@@ -515,7 +515,7 @@ Options List
 * ``warning_flags``: [ ``string`` ]
     Additional compiler flags passed to the C/C++ compiler to enable
     extra warnings. Used only when compiling source code that is part of
-    Cantera (e.g. excluding code in the 'ext' directory).
+    Cantera (for example, excluding code in the 'ext' directory).
 
     - default: ``''``
 
@@ -539,15 +539,15 @@ Options List
 
 * ``boost_inc_dir``: [ ``/path/to/boost_inc_dir`` ]
     Location of the Boost header files. Not needed if the headers are
-    installed in a standard location, e.g. ``/usr/include``.
+    installed in a standard location such as ``/usr/include``.
 
     - default: ``''``
 
 .. _stage-dir:
 
 * ``stage_dir``: [ ``/path/to/stage_dir`` ]
     Directory relative to the Cantera source directory to be used as a
-    staging area for building e.g., a Debian package. If specified,
+    staging area for building for example, a Debian package. If specified,
     ``scons install`` will install files to ``stage_dir/prefix/...``.
 
     - default: ``''``
@@ -562,7 +562,7 @@ Options List
 .. _gtest-flags:
 
 * ``gtest_flags``: [ ``string`` ]
-    Additional options passed to each GTest test suite, e.g.
+    Additional options passed to each GTest test suite, such as
     `--gtest_filter=*pattern*`. Separate multiple options with spaces.
 
 .. _renamed-shared-libraries:
@@ -581,7 +581,7 @@ Options List
 
 * ``versioned_shared_library``: [ ``yes`` | ``no`` ]
     If enabled, create a versioned shared library, with symlinks to the
-    more generic library name, e.g. ``libcantera_shared.so.2.4.0`` as the
+    more generic library name, for example ``libcantera_shared.so.2.4.0`` as the
     actual library and ``libcantera_shared.so`` and ``libcantera_shared.so.2``
     as symlinks.
 
@@ -591,7 +591,7 @@ Options List
 
 * ``layout``: [ ``standard`` | ``compact`` | ``debian`` ]
     The layout of the directory structure. 'standard' installs files to
-    several subdirectories under 'prefix', e.g. $prefix/bin,
+    several subdirectories under 'prefix' -- for example, $prefix/bin,
     $prefix/include/cantera, $prefix/lib. This layout is best used in
     conjunction with 'prefix'='/usr/local'. 'compact' puts all installed
     files in the subdirectory defined by 'prefix'. This layout is best

pages/compiling/configure-build-dev.rst

@@ -21,7 +21,7 @@ Determine configuration options
   see all of the options on the :ref:`Configuration Options <scons-config-dev>` page.
 
 * Configuration options are specified as additional arguments to the ``scons``
-  command, e.g.:
+  command. For example:
 
   .. code:: bash
 
@@ -48,7 +48,7 @@ Determine configuration options
      scons command option_name=
 
 * Sometimes, changes in your environment can cause SCons's configuration tests
-  (e.g., checking for libraries or compiler capabilities) to unexpectedly fail.
+  (for example, checking for libraries or compiler capabilities) to unexpectedly fail.
   To force SCons to re-run these tests rather than trusting the cached results,
   run scons with the option ``--config=force``.
 
@@ -111,7 +111,7 @@ Windows Only Options
 * In Windows there aren't any proper default locations for many of the packages
   that Cantera depends on, so you will need to specify these paths explicitly.
 
-* Remember to put double quotes around any paths with spaces in them, e.g.
+* Remember to put double quotes around any paths with spaces in them, such as
   ``"C:\Program Files"``.
 
 * By default, SCons attempts to use the same architecture as the copy of Python
@@ -169,8 +169,8 @@ Less Common Options
 Build Commands
 ==============
 
-The following options are possible as commands to SCons, i.e., the first
-argument after ``scons``:
+The following options are possible as commands to SCons (that is, the first
+argument after ``scons``):
 
 .. code:: bash
 
@@ -210,7 +210,7 @@ argument after ``scons``:
 
 * ``scons <command> dump``
     Dump the state of the SCons environment to the
-    screen instead of doing ``<command>``, e.g.
+    screen instead of doing ``<command>``, for example,
     ``scons build dump``. For debugging purposes.
 
 * ``scons samples``