setting conf file; documentation update

ajjackson · Feb 9, 2016 · 6c69ff2 · 6c69ff2
1 parent b083e75
commit 6c69ff2
Show file tree

Hide file tree

Showing 7 changed files with 82 additions and 18 deletions.
diff --git a/addons/vsim2blender/settings.conf b/addons/vsim2blender/settings.conf
@@ -0,0 +1,3 @@
+[general]
+
+background = 0.5 0.5 0.5
diff --git a/docs/Config.rst b/docs/Config.rst
@@ -0,0 +1,61 @@
+
+Configuration files
+===================
+
+Plain-text configuration files are used to provide supporting data and allow per-user tweaking.
+In addition to the provided files **settings.conf** and **elements.conf**, which are found in the ``addons/vsim2blender`` folder of the project, the user can maintain their own configuration file in this format. When this file is provided via the ``--config`` flag of the :ref:`CLI` or using the :func:`vsim2blender.read_config` function of the Python library, user settings will take precedent over the defaults.
+
+The format of this files is a typical plain text .ini format and is implemented with `configparser <https://docs.python.org/3.5/library/configparser.html>`_.
+Parameters are grouped into *sections* with a header in square brackets; the parameters themselves are separated from their values with ``=`` or ``:`` markers
+
+::
+
+   [Header]
+   
+   Like = this
+   Or: this
+
+   # And comments are indicated with a '#'
+   ; or a ';'
+
+Parameters and section headers are *case-sensitive*, and are lower-case except for the names of elements, which follow their usual capitalisation rule.
+
+Settings
+--------
+
+**settings.conf** currently hosts one section, ``[General]``, with the following parameters:
+
+* ``background = R G B`` The background colour is set with three floating point RGB values. These range between 0 and 1.
+
+Elements
+--------
+
+Data for each element is included in the ``elements.conf``
+configuration file.  Relative atomic masses are drawn from standard
+reference data. [1]_ Where this reference gives a range and/or the
+relative abundance of isotopes is unknown, a simple mean was taken.
+
+::
+
+    [masses]
+    C = 12.0106   # The mass of carbon is a floating-point number in a.m.u.
+
+Atomic radii are drawn from a recent study encompassing elements with atomic numbers up to 96. [2]_
+
+::
+
+    [radii]
+    Ac = 2.15  # The covalent radius of Ac is a floating-point number in angstroms
+
+Colours are assigned somewhat arbitrarily for a handful of elements
+which have been used in WMD Group publications. Suggestions are
+welcome for a more mainstream pallette. The values are RGB tuples, with values ranging from 0 to 1.
+
+::
+
+    [colours]
+    Cu = 0.8 0.3 0.1
+
+.. [1] www.nist.gov/pml/data/comp  J. S. Coursey, D. J. Schwab, J. J. Tsai, and R. A. Dragoset, NIST Physical Measurement Laboratory
+.. [2] http://dx.doi.org/10.1039/B801115J B. Cordero *et al.* (2008) *Dalton Trans.* **2008** (21) 2832-2838
+
diff --git a/docs/bpy.rst b/docs/bpy.rst
@@ -6,15 +6,22 @@ The interface with Blender is managed as a Python add-on module :mod:`~vsim2blen
 See the `module index <py-modindex.html>`_ for the documentation of these modules.
 The :ref:`cli` works by generating a temporary script file and executing the script with Blender.
 Advanced Blender users may prefer to directly import the ``vsim2blender`` module and use it with Blender's scripting tools.
+The key plotting tools are all in :mod:`~vsim2blender.plotter`, with supporting functions in the other modules.
+
+Top-level functions
+-------------------
+
+.. automodule:: vsim2blender
+   :members:                
+
 
 List of modules
 ---------------
-
 .. toctree::
    :maxdepth: 2
 
    vsim2blender/arrows
    vsim2blender/ascii_importer
    vsim2blender/plotter
-   vsim2blender/masses
+
 
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,8 +3,11 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to ascii-phonons's documentation!
-=========================================
+ascii-phonons: Documentation
+============================
+
+.. figure:: ../images/comof_phonon.gif
+   :align: center
 
 Contents:
 
@@ -16,6 +19,7 @@ Contents:
    CLI
    GUI
    bpy
+   Config
    Development
    License
 

diff --git a/docs/vsim2blender/ascii_importer.rst b/docs/vsim2blender/ascii_importer.rst
@@ -1,4 +1,4 @@
-ascii file importer
+Ascii file importer
 ===================
 .. automodule:: ascii_importer
    :members:
diff --git a/docs/vsim2blender/masses.rst b/docs/vsim2blender/masses.rst
diff --git a/docs/vsim2blender/plotter.rst b/docs/vsim2blender/plotter.rst
@@ -3,8 +3,8 @@ Plotter
 
 Commands for adding atoms to the scene and animating them.
 
-Animation
----------
+Mathematics
+-----------
 
 The key equation is: [1]_