more updates to docs

geodynamics · Aug 2, 2021 · 24ac020 · 24ac020
1 parent d669f8c
commit 24ac020
Show file tree

Hide file tree

Showing 24 changed files with 158 additions and 108 deletions.
diff --git a/burnman/__init__.py b/burnman/__init__.py
@@ -98,7 +98,7 @@
 2. Clone the BurnMan repository ``git clone https://github.com/geodynamics/burnman.git``
 3. Go to the Burnman examples directory and type:
    ``python example_beginner.py``
-Figures should show up, indicating that it is working.
+   Figures should show up, indicating that it is working.
 
 
 Install on a Mac
@@ -114,7 +114,7 @@
 4. Install the latest Sympy from http://sourceforge.net/projects/sympy/files/
 5. Install the latest Matplotlib from http://sourceforge.net/projects/matplotlib/files/matplotlib/matplotlib-1.1.1/
 6. Clone the BurnMan repository ``git clone https://github.com/geodynamics/burnman.git``
-7. Go to the Burnman examples directory and type `python example_beginner.py`
+7. Go to the Burnman examples directory and type ``python example_beginner.py``
    Figures should show up, indicating that it is working.
 
 Install under Windows
@@ -140,11 +140,12 @@
 
   - Cottaar, S., Heister, T., Myhill, R., Rose, I., and Unterborn, C. (2017):
     BurnMan v0.10.0 [Software]. Computational Infrastructure for Geodynamics. Zenodo.
-    `(link) <https://doi.org/10.5281/zenodo.546210>`_
+    `(https://doi.org/10.5281/zenodo.546210) <https://doi.org/10.5281/zenodo.546210>`_
 
   - Cottaar S., Heister, T., Rose, I., and Unterborn, C., 2014, BurnMan: A
     lower mantle mineral physics toolkit, Geochemistry, Geophysics, and
-    Geosystems, 15(4), 1164-1179 `(link) <https://doi.org/10.1002/2013GC005122>`_
+    Geosystems, 15(4), 1164-1179 `(https://doi.org/10.1002/2013GC005122)
+    <https://doi.org/10.1002/2013GC005122>`_
 
 Contributing to BurnMan
 -----------------------

diff --git a/burnman/minerals/DKS_2013_liquids.py b/burnman/minerals/DKS_2013_liquids.py
@@ -3,8 +3,10 @@
 # Released under GPL v2 or later.
 
 """
-DKS_2013
-Liquids from de Koker and Stixrude (2013) FPMD simulations
+DKS_2013_liquids
+^^^^^^^^^^^^^^^^
+
+Liquids from de Koker and Stixrude (2013) FPMD simulations.
 """
 
 from ..mineral import Mineral

diff --git a/burnman/minerals/DKS_2013_solids.py b/burnman/minerals/DKS_2013_solids.py
@@ -4,6 +4,8 @@
 
 """
 DKS_2013_solids
+^^^^^^^^^^^^^^^
+
 Solids from de Koker and Stixrude (2013) FPMD simulations
 """
 

diff --git a/burnman/minerals/HHPH_2013.py b/burnman/minerals/HHPH_2013.py
@@ -5,10 +5,12 @@
 
 """
 HHPH_2013
-Minerals from Holland et al 2013 and references therein
+^^^^^^^^^
+
+Minerals from Holland et al. (2013) and references therein.
 The values in this document are all in S.I. units,
-unlike those in the original paper
-File autogenerated using HHPHdata_to_burnman.py
+unlike those in the original paper.
+File autogenerated using HHPHdata_to_burnman.py.
 """
 from __future__ import absolute_import
 

diff --git a/burnman/minerals/HP_2011_ds62.py b/burnman/minerals/HP_2011_ds62.py
@@ -5,11 +5,13 @@
 
 """
 HP_2011 (ds-62)
-Endmember minerals from Holland and Powell 2011 and references therein
-Update to dataset version 6.2
+^^^^^^^^^^^^^^^
+
+Endmember minerals from Holland and Powell 2011 and references therein.
+Update to dataset version 6.2.
 The values in this document are all in S.I. units,
-unlike those in the original tc-ds62.txt
-File autogenerated using HPdata_to_burnman.py
+unlike those in the original tc-ds62.txt.
+File autogenerated using HPdata_to_burnman.py.
 """
 
 from ..mineral import Mineral

diff --git a/burnman/minerals/HP_2011_fluids.py b/burnman/minerals/HP_2011_fluids.py
@@ -6,28 +6,38 @@
 """
 
 HP_2011_fluids
-^^^^^^^^
+^^^^^^^^^^^^^^
 
 Fluids from Holland and Powell 2011 and references therein.
-CORK parameters:
-CHO gases from Holland and Powell, 1991. ["CO2",304.2,0.0738],["CH4",190.6,0.0460],["H2",41.2,0.0211],["CO",132.9,0.0350]
-H2O and S2 from Wikipedia, 2012/10/23. ["H2O",647.096,0.22060],["S2",1314.00,0.21000]
-H2S from ancyclopedia.airliquide.com, 2012/10/23. ["H2S",373.15,0.08937]
-
-NB: Units for cork[i] in Holland and Powell datasets are
-a = kJ^2/kbar*K^(1/2)/mol^2 -> multiply by 1e-2
-b = kJ/kbar/mol -> multiply by 1e-5
-c = kJ/kbar^1.5/mol -> multiply by 1e-9
-d = kJ/kbar^2/mol -> multiply by 1e-13
-
-Individual terms are divided through by P, P, P^1.5, P^2, so
-[0][j] -> multiply by 1e6
-[1][j] -> multiply by 1e3
-[2][j] -> multiply by 1e3
-[3][j] -> multiply by 1e3
-
-cork_P: kbar -> multiply by 1e8
+CORK parameters are taken from various sources.
+
+CHO gases from Holland and Powell, 1991:
+  - ["CO2",304.2,0.0738]
+  - ["CH4",190.6,0.0460]
+  - ["H2",41.2,0.0211]
+  - ["CO",132.9,0.0350]
+
+H2O and S2 from Wikipedia, 2012/10/23:
+  - ["H2O",647.096,0.22060]
+  - ["S2",1314.00,0.21000]
+
+H2S from ancyclopedia.airliquide.com, 2012/10/23:
+  - ["H2S",373.15,0.08937]
+
+NB: Units for cork[i] in Holland and Powell datasets are:
+  - a = kJ^2/kbar*K^(1/2)/mol^2: multiply by 1e-2
+  - b = kJ/kbar/mol: multiply by 1e-5
+  - c = kJ/kbar^1.5/mol: multiply by 1e-9
+  - d = kJ/kbar^2/mol: multiply by 1e-13
+
+Individual terms are divided through by P, P, P^1.5, P^2, so:
+  - [0][j]: multiply by 1e6
+  - [1][j]: multiply by 1e3
+  - [2][j]: multiply by 1e3
+  - [3][j]: multiply by 1e3
+  - cork_P is given in kbar: multiply by 1e8
 """
+
 from __future__ import absolute_import
 
 from ..mineral import Mineral

diff --git a/burnman/minerals/JH_2015.py b/burnman/minerals/JH_2015.py
@@ -5,6 +5,8 @@
 
 """
 JH_2015
+^^^^^^^
+
 Solid solutions from Jennings and Holland, 2015 and references therein
 (10.1093/petrology/egv020).
 The values in this document are all in S.I. units,

diff --git a/burnman/minerals/RS_2014_liquids.py b/burnman/minerals/RS_2014_liquids.py
@@ -3,8 +3,10 @@
 # Released under GPL v2 or later.
 
 """
-RS_2014
-Liquids from Ramo and Stixrude (2014) FPMD simulations
+RS_2014_liquids
+^^^^^^^^^^^^^^^
+
+Liquids from Ramo and Stixrude (2014) FPMD simulations.
 There are some typos in the article which have been corrected where marked
 with the help of David Munoz Ramo.
 """

diff --git a/burnman/minerals/SLB_2011.py b/burnman/minerals/SLB_2011.py
@@ -5,8 +5,10 @@
 
 """
 SLB_2011
-Minerals from Stixrude & Lithgow-Bertelloni 2011 and references therein
-File autogenerated using SLBdata_to_burnman.py
+^^^^^^^^
+
+Minerals from Stixrude & Lithgow-Bertelloni 2011 and references therein.
+File autogenerated using SLBdata_to_burnman.py.
 """
 
 from __future__ import absolute_import

diff --git a/burnman/tools.py b/burnman/tools.py
@@ -882,9 +882,6 @@ def compare_l2(depth, calc, obs):
     """
     Computes the L2 norm for N profiles at a time (assumed to be linear between points).
 
-    .. math:: math does not work yet...
-    \sum_{i=1}^{\\infty} x_{i}
-
     :type depths: array of float
     :param depths: depths. :math:`[m]`
     :type calc: list of arrays of float

diff --git a/sphinx/api.rst b/sphinx/api.rst
@@ -3,7 +3,6 @@ Autogenerated Full API
 
 
 .. toctree::
-   main
    materials
    eos
    solution_models

diff --git a/sphinx/averaging.rst b/sphinx/averaging.rst
@@ -1,38 +1,44 @@
 Averaging Schemes
 =================
 
-Given a set of mineral physics parameters and an equation of state we can calculate the density, bulk, and shear modulus for a given phase. 
-However, as soon as we have a composite material (e.g., a rock), the determination of elastic properties become more complicated. 
-The bulk and shear modulus of a rock are dependent on the specific geometry of the grains in the rock, so there is no general 
-formula for its averaged elastic properties.  Instead, we must choose from a number of averaging schemes if we want a single value, 
-or use bounding methods to get a range of possible values.  The module :mod:`burnman.averaging_schemes` provides a number of different 
+Given a set of mineral physics parameters and an equation of state we can calculate the density, bulk, and shear modulus for a given phase.
+However, as soon as we have a composite material (e.g., a rock), the determination of elastic properties become more complicated.
+The bulk and shear modulus of a rock are dependent on the specific geometry of the grains in the rock, so there is no general
+formula for its averaged elastic properties.  Instead, we must choose from a number of averaging schemes if we want a single value,
+or use bounding methods to get a range of possible values.  The module :mod:`burnman.averaging_schemes` provides a number of different
 average and bounding schemes for determining a composite rock's physical parameters.
 
 Base class
 -----------
+
 .. autoclass:: burnman.averaging_schemes.AveragingScheme
 
 Voigt bound
 -----------
+
 .. autoclass:: burnman.averaging_schemes.Voigt
 
 Reuss bound
 -----------
+
 .. autoclass:: burnman.averaging_schemes.Reuss
 
 Voigt-Reuss-Hill average
 ------------------------
+
 .. autoclass:: burnman.averaging_schemes.VoigtReussHill
 
 Hashin-Shtrikman upper bound
 ----------------------------
+
 .. autoclass:: burnman.averaging_schemes.HashinShtrikmanUpper
 
 Hashin-Shtrikman lower bound
 ----------------------------
+
 .. autoclass:: burnman.averaging_schemes.HashinShtrikmanLower
 
 Hashin-Shtrikman arithmetic average
 -----------------------------------
-.. autoclass:: burnman.averaging_schemes.HashinShtrikmanAverage
 
+.. autoclass:: burnman.averaging_schemes.HashinShtrikmanAverage
diff --git a/sphinx/composites.rst b/sphinx/composites.rst
@@ -5,4 +5,3 @@ Base class
 ----------
 
 .. autoclass:: burnman.composite.Composite
-
diff --git a/sphinx/conf.py b/sphinx/conf.py
@@ -13,6 +13,7 @@
 import os
 import sys
 sys.path.insert(0, os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath('../examples'))
 
 import burnman
 import burnman.version
@@ -34,16 +35,18 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-    'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.mathjax',
-    'numpydoc', 'sphinx.ext.intersphinx', 'sphinx.ext.ifconfig', 'sphinx.ext.inheritance_diagram',
-    'sphinx.ext.viewcode', 'sphinxcontrib.bibtex']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary',
+              'sphinx.ext.mathjax', 'numpydoc', 'sphinx.ext.intersphinx',
+              'sphinx.ext.ifconfig', 'sphinx.ext.inheritance_diagram',
+              'sphinx.ext.viewcode', 'sphinxcontrib.bibtex']
 bibtex_bibfiles = ['ref.bib']
 
 numpydoc_show_class_members = False
 
-autodoc_default_flags = [
-    'members', 'undoc-members', 'show-inheritance', 'inherited-members']
+autodoc_default_options = {'members': True,
+                           'undoc-members': True,
+                           'show-inheritance': True,
+                           'inherited-members': True}
 
 autodoc_member_order = 'bysource'
 
@@ -213,8 +216,7 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-    ('index_pdf', 'BurnMan.tex', u'BurnMan Documentation',
-     u'Sanne Cottaar, Timo Heister, Robert Myhill, Ian Rose, Cayman Unterborn', 'manual'),
+    ('index_pdf', 'BurnMan.tex', u'BurnMan Documentation', author, 'manual'),
 ]
 
 
@@ -244,8 +246,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'burnman', u'BurnMan Documentation',
-     [u'Sanne Cottaar, Timo Heister, Robert Myhill, Ian Rose, Cayman Unterborn'], 1)
+    ('index', 'burnman', u'BurnMan Documentation', [author], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -259,7 +260,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
     ('index', 'BurnMan', u'BurnMan Documentation',
-     u'Sanne Cottaar, Timo Heister, Robert Myhill, Ian Rose, Cayman Unterborn', 'BurnMan', 'One line description of project.',
+     author, 'BurnMan', 'One line description of project.',
      'Miscellaneous'),
 ]
 
@@ -272,6 +273,5 @@
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 # texinfo_show_urls = 'footnote'
 
-
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
diff --git a/sphinx/eos.rst b/sphinx/eos.rst
@@ -30,7 +30,7 @@ Reciprocal K-prime
 ------------------
 
 .. autoclass:: burnman.eos.RKprime
-	       
+
 Stixrude and Lithgow-Bertelloni Formulation
 -------------------------------------------
 
@@ -69,4 +69,3 @@ Anderson and Ahrens (1994)
 CoRK
 ----
 .. autoclass:: burnman.eos.CORK
-