CitrineInformatics · kroenlein · Jan 31, 2024 · Jan 8, 2024 · Jan 9, 2024 · Jan 9, 2024
diff --git a/docs/source/_static/favicon.png b/docs/source/_static/favicon.png
diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -10,9 +10,10 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import gemd
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../../gemd'))
+sys.path.insert(0, os.path.abspath('../..'))
 
 
 # -- Project information -----------------------------------------------------
@@ -21,8 +22,10 @@
 copyright = '2020, Citrine Informatics'
 author = 'Citrine Informatics'
 
-# The full version, including alpha/beta/rc tags
-release = '0.0.0'
+# The short X.Y version.
+version = gemd.__version__
+# The full version, including alpha/beta/rc tags.
+release = gemd.__version__
 
 
 # -- General configuration ---------------------------------------------------
@@ -43,8 +46,9 @@
 # See: https://github.com/sphinx-contrib/apidoc
 apidoc_module_dir = '../../gemd'
 apidoc_output_dir = 'reference'
-apidoc_excluded_paths = ['tests']
+apidoc_excluded_paths = ['tests', '*impl*']
 apidoc_separate_modules = True
+apidoc_toc_file = False
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -76,6 +80,9 @@
 # autodoc_mock_imports allows Sphinx to ignore any external modules listed in the array
 autodoc_mock_imports = []
 
+html_favicon = '_static/favicon.png'
+html_logo = '_static/logo.png'
 html_theme_options = {
-    "sticky_navigation": False
-}
+    'sticky_navigation': False,
+    'logo_only': True
+}
diff --git a/docs/source/depth/index.rst b/docs/source/depth/index.rst
diff --git a/docs/source/depth/unit_parsing.rst b/docs/source/depth/unit_parsing.rst
@@ -7,8 +7,13 @@ By default, Pint supports a larger set of units than the Citrine Platform.
 Therefore, we include a custom unit definition file in gemd-python: `citrine_en.txt`_.
 This file contains the most commonly used units and will grow over time.
 
+In support of common patterns in materials science, we permit including scaling factors in a unit of measure.
+For example, industrial researchers may have recorded historical data as ``g / 2.5 cm``.
+While this could be converted a simple SI expression, that would prevent researchers from representing the data
+as originally reported, thus creating a potential source of error during the input process.
+
 Requests for support of additional units can be made by opening an issue in the `gemd-python repository`_ on github.
 
-.. _Pint: https://pint.readthedocs.io/en/0.9/
+.. _Pint: https://pint.readthedocs.io/en/0.20/
 .. _citrine_en.txt: https://github.com/CitrineInformatics/gemd-python/blob/main/gemd/units/citrine_en.txt
 .. _GEMD-python repository: https://github.com/CitrineInformatics/gemd-python
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,23 +6,46 @@
 Welcome to the GEMD-Python Documentation!
 ===================================================
 
-``gemd`` is the Python implementation of the Citrine data model, the full documentation of which
-can be found `here <https://citrineinformatics.github.io/gemd-docs/>`_.
+This site documents the Python implementation of the Graphical Expression of Materials Data (GEMD) model.
+GEMD is an open source data format developed by `Citrine Informatics <https://citrine.io/>`_ for representing
+data in materials in a `FAIR <https://www.go-fair.org/fair-principles/>`_ and transformable manner.
+Documentation of the underlying data model can be found `here <https://citrineinformatics.github.io/gemd-docs/>`_.
 
 To learn about the details of specific classes, please see the module index.
 
+Installation
+------------
+
+The latest release can be installed via `pip`:
+
+.. code:: bash
+
+  pip install gemd
+
+or a specific version can be installed, for example:
+
+.. code:: bash
+
+  pip install gemd==1.17.1
+
 Table of Contents
 -----------------
 
 .. toctree::
    :maxdepth: 2
    :numbered: 4
 
-   depth/index
+   depth/unit_parsing
+   depth/serialization
 
-Indices and tables
+Indices
 ------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+
+.. toctree::
+   :maxdepth: 1
+
+   reference/gemd
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
diff --git a/docs/source/setup.rst b/docs/source/setup.rst
diff --git a/gemd/__init__.py b/gemd/__init__.py
@@ -1,5 +1,5 @@
 """Data concepts library."""
-# flake8: noqa
+from .__version__ import __version__  # noqa: F401
 from .entity import Condition, Parameter, Property, PropertyAndConditions, \
     CategoricalBounds, CompositionBounds, IntegerBounds, \
     MolecularStructureBounds, RealBounds, \
@@ -12,7 +12,7 @@
     UniformInteger, DiscreteCategorical, NominalCategorical, \
     EmpiricalFormula, NominalComposition, InChI, Smiles, \
     LinkByUID, \
-    FileLink
+    FileLink  # noqa: F401
 
 __all__ = ["Condition", "Parameter", "Property", "PropertyAndConditions",
            "CategoricalBounds", "CompositionBounds", "IntegerBounds",

diff --git a/gemd/__version__.py b/gemd/__version__.py
@@ -0,0 +1 @@
+__version__ = "1.18.1"
diff --git a/gemd/builders/__init__.py b/gemd/builders/__init__.py
@@ -1,2 +1,6 @@
 # flake8: noqa
 from .impl import make_node, add_edge, add_measurement, add_attribute, make_attribute, make_value
+
+__all__ = [
+    "make_node", "add_edge", "add_measurement", "add_attribute", "make_attribute", "make_value"
+]
diff --git a/gemd/builders/impl.py b/gemd/builders/impl.py
@@ -18,6 +18,10 @@
 
 from typing import Union, List
 
+__all__ = [
+    "make_node", "add_edge", "add_measurement", "add_attribute", "make_attribute", "make_value"
+]
+
 
 def make_node(name: str,
               *,
@@ -30,19 +34,22 @@ def make_node(name: str,
     Parameters
     ----------
     name: str
-        Name of the MaterialRun and MaterialSpec.
+        Name of the :class:`~gemd.entity.object.material_run.MaterialRun`
+        and :class:`~gemd.entity.object.material_spec.MaterialSpec`.
     process_name: str
-        Name of the ProcessRun and ProcessSpec.  Defaults to
-        `process_template.name` if `process_template` is defined, else `name`.
-    process_template: ProcessTemplate
-        ProcessTemplate for the quadruple.
-    material_template: MaterialTemplate
-        MaterialTemplate for the quadruple.
+        Name of the :class:`~gemd.entity.object.process_run.ProcessRun`
+        and :class:`~gemd.entity.object.process_spec.ProcessSpec`.  Defaults to
+        :attr:`process_template.name` if `process_template` is defined, else `name`.
+    process_template: ~gemd.entity.template.process_template.ProcessTemplate
+        :class:`~gemd.entity.template.process_template.ProcessTemplate` for the quadruple.
+    material_template: ~gemd.entity.template.material_template.MaterialTemplate
+        :class:`~gemd.entity.template.material_template.MaterialTemplate` for the quadruple.
 
     Returns
     --------
-    MaterialRun
-        A MaterialRun with linked processes, specs and templates
+    ~gemd.entity.object.material_run.MaterialRun
+        A :class:`~gemd.entity.object.material_run.MaterialRun` with linked processes,
+        specs and templates
 
     """
     if process_name is None:
@@ -90,28 +97,45 @@ def add_edge(input_material: MaterialRun,
 
     Parameters
     ----------
-    input_material: MaterialRun
-        The `material` for the returned IngredientRun
-    output_material: MaterialRun
-        The `process` for the returned IngredientRun will be
-        `output_material.process`
+    input_material: ~gemd.entity.object.material_run.MaterialRun
+        The :attr:`~gemd.entity.object.ingredient_run.IngredientRun.material`
+        for the returned
+        :class:`~gemd.entity.object.ingredient_run.IngredientRun`
+    output_material: ~gemd.entity.object.material_run.MaterialRun
+        The :attr:`~gemd.entity.object.ingredient_run.IngredientRun.process`
+        for the returned
+        :class:`~gemd.entity.object.ingredient_run.IngredientRun`
+        will be `output_material.process`
     name: str
         The ingredient name.  Defaults to `input_material.name`.
-    mass_fraction: float or ContinuousValue
-        The mass fraction of the Ingredient Run.  0 <= x <= 1
-    number_fraction: float or ContinuousValue
-        The number fraction of the Ingredient Run.  0 <= x <= 1
-    volume_fraction: float or ContinuousValue
-        The volume fraction of the Ingredient Run.  0 <= x <= 1
-    absolute_quantity: float or ContinuousValue
-        The absolute quantity.  0 <= x
+    mass_fraction: float or ~gemd.entity.value.continuous_value.ContinuousValue
+        The :attr:`~gemd.entity.object.ingredient_run.IngredientRun.mass_fraction`
+        of the returned
+        :class:`~gemd.entity.object.ingredient_run.IngredientRun`.`
+        0 <= x <= 1
+    number_fraction: float or ~gemd.entity.value.continuous_value.ContinuousValue
+        The :attr:`~gemd.entity.object.ingredient_run.IngredientRun.number_fraction`
+        of the returned
+        :class:`~gemd.entity.object.ingredient_run.IngredientRun`.
+        0 <= x <= 1
+    volume_fraction: float or ~gemd.entity.value.continuous_value.ContinuousValue
+        The :attr:`~gemd.entity.object.ingredient_run.IngredientRun.volume_fraction`
+        of the returned
+        :class:`~gemd.entity.object.ingredient_run.IngredientRun`.
+        0 <= x <= 1
+    absolute_quantity: float or ~gemd.entity.value.continuous_value.ContinuousValue
+        The :attr:`~gemd.entity.object.ingredient_run.IngredientRun.absolute_quantity`
+        of the returned
+        :class:`~gemd.entity.object.ingredient_run.IngredientRun`.
+        0 <= x
     absolute_units: str
         The absolute units.  Required if absolute_quantity is provided as a float
 
     Returns
     --------
-    IngredientRun
-        A IngredientRun with linked processes, specs and materials
+    ~gemd.entity.object.ingredient_run.IngredientRun
+        A :class:`~gemd.entity.object.ingredient_run.IngredientRun`
+        with linked processes, specs and materials
 
     """
     output_spec = output_material.spec
@@ -171,24 +195,33 @@ def add_measurement(material: MaterialRun,
                     attributes: List[BaseAttribute] = None,
                     ) -> MeasurementRun:
     """
-    Add a measurement run-spec set to a MaterialRun.
+    Add a measurement run-spec set to a :class:`~gemd.entity.object.material_run.MaterialRun`.
 
     Parameters
     ----------
-    material: MaterialRun
-        The `material` for the returned MeasurementRun
+    material: ~gemd.entity.object.material_run.MaterialRun
+        The :attr:`~gemd.entity.object.measurement_run.MeasurementRun.material`
+        for the returned
+        :class:`~gemd.entity.object.measurement_run.MeasurementRun`
     name: str
-        The name of the measurement.  Defaults to
-        `template.name` if `template` is defined.
-    template: MeasurementTemplate
-        The MeasurementTemplate.
+        The :attr:`~gemd.entity.object.measurement_run.MeasurementRun.name`
+        of the measurement.  Defaults to `template.name` if `template` is defined.
+    template: ~gemd.entity.template.measurement_template.MeasurementTemplate
+        The :attr:`~gemd.entity.object.measurement_run.MeasurementRun.template`
+        for the returned
+        :class:`~gemd.entity.object.measurement_run.MeasurementRun`
     attributes: List[BaseAttribute]
-        Attributes you want associated with this MeasurementRun.
+        Attributes you want associated with this
+        :class:`~gemd.entity.object.measurement_run.MeasurementRun`.  These can be
+        :class:`Conditions <gemd.entity.attribute.condition.Condition>`,
+        :class:`Parameters <gemd.entity.attribute.parameter.Parameter>`,
+        and/or :class:`Properties <gemd.entity.attribute.property.Property>`.
 
     Returns
     --------
-    MeasurementRun
-        A MeasurementRun with linked material, spec and template
+    ~gemd.entity.object.measurement_run.MeasurementRun
+        A :class:`~gemd.entity.object.measurement_run.MeasurementRun`
+        with linked material, spec and template
 
     """
     if name is None:
@@ -226,10 +259,10 @@ def add_attribute(target: Union[HasProperties, HasConditions, HasParameters],
     target: BaseObject
         The object to attach the attribute to
     template: AttributeTemplate
-        The AttributeTemplate for the attribute.
-    value: Union[BaseValue, str, float, int]
-        The value for the attribute.  Accepts any GEMD Value type, or will
-        attempt to generate an appropriate Value given a str, float or int.
+        The :attr:`~BaseAttribute.template` for the attribute.
+    value: BaseValue, str, float,  or int
+        The :attr:`~BaseAttribute.value` for the attribute.  Accepts any GEMD Value type, or will
+        attempt to generate an appropriate :class:`BaseValue` subclass given a str, float or int.
 
     Returns
     --------
@@ -272,9 +305,9 @@ def make_attribute(template: Union[PropertyTemplate, ConditionTemplate, Paramete
     Parameters
     ----------
     template: AttributeTemplate
-        The AttributeTemplate for the attribute.
-    value: Union[BaseValue, str, float, int]
-        The value for the attribute.  Accepts any GEMD Value type, or will
+        The :attr:`~BaseAttribute.template` for the attribute.
+    value: BaseValue, str, float, or int
+        The :attr:`~BaseAttribute.value` for the attribute.  Accepts any GEMD Value type, or will
         attempt to generate an appropriate Value given a str, float or int.
 
     Returns
@@ -307,7 +340,7 @@ def make_value(value: Union[str, float, int],
 
     Parameters
     ----------
-    value: Union[str, float, int]
+    value: str, float, or int
         The primitive type to wrap in a Value
     bounds: BaseBounds
         The bounds type to determine which value type we want to coerce the value into

diff --git a/gemd/demo/cake.py b/gemd/demo/cake.py
@@ -25,6 +25,10 @@
 
 from gemd.util.impl import recursive_foreach
 
+__all__ = [
+    "change_scope", "get_demo_scope", "get_template_scope", "import_toothpick_picture",
+    "make_cake_templates", "make_cake_spec", "make_cake"
+]
 
 # For now, module constant, though likely this should get promoted to a package level
 DEMO_SCOPE = 'citrine-demo'

diff --git a/gemd/demo/strehlow_and_cook.py b/gemd/demo/strehlow_and_cook.py
@@ -37,6 +37,11 @@
 FULL_TABLE = "strehlow_and_cook.pif"
 SMALL_TABLE = "strehlow_and_cook_small.pif"
 
+__all__ = [
+    "import_table", "minimal_subset", "make_templates", "make_strehlow_objects",
+    "make_strehlow_table", "make_display_table"
+]
+
 
 def import_table(filename=SMALL_TABLE):
     """Return the deserialized JSON table."""
@@ -398,6 +403,7 @@ def make_display_table(structured):
     (CSV of scalar values) based upon some standard assumptions about how it should be displayed.
 
     :param structured: A structured table, such as generated by make_strehlow_table
+
     :return
     """
     table = [[]]