Remove documentation build bugs (#204)

Boost Sphinx to 5; Remove documentation build bugs

Author: kroenlein

docs/source/_static/favicon.png

@@ -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
+}

docs/source/_static/logo.png

@@ -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

docs/source/conf.py

@@ -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

docs/source/depth/index.rst

@@ -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",

docs/source/depth/unit_parsing.rst

@@ -0,0 +1 @@
+__version__ = "1.18.1"