Merge pull request #145 from CitrineInformatics/docs-cleanup

Docs cleanup

Author: bfolie

docs/Makefile

@@ -8,6 +8,8 @@ SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = _build
 
+export SPHINX_APIDOC_OPTIONS=members,undoc-members,inherited-members,show-inheritance
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/_static/css/custom.css

@@ -0,0 +1,19 @@
+/* Displays method signatures with one parameter per line.
+See https://github.com/sphinx-doc/sphinx/issues/1514 */
+
+/* Newline (\a) and spaces (\20) before each parameter */
+.sig-param::before {
+    content: "\a\20\20\20\20\20\20\20\20\20\20\20\20\20\20\20\20";
+    white-space: pre;
+}
+
+/* Newline after the last parameter (so the closing bracket is on a new line) */
+dt em.sig-param:last-of-type::after {
+    content: "\a";
+    white-space: pre;
+}
+
+/* To have blue background be width of the block (instead of width of content) */
+dl.class > dt:first-of-type {
+    display: block !important;
+}

docs/source/conf.py

@@ -32,7 +32,8 @@
 # ones.
 extensions = [
     'sphinxcontrib.apidoc',
-    'sphinx.ext.napoleon'
+    'sphinx.ext.napoleon',
+    'sphinx.ext.intersphinx'
 ]
 
 # Use the sphinxcontrib.apidoc extension to wire in the sphinx-apidoc invocation
@@ -59,12 +60,22 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-# autodoc_mock_imports allows Spyinx to ignore any external modules listed in the array
+# These paths are either relative to html_static_path or fully qualified paths (eg. https://...)
+html_css_files = [
+    'css/custom.css',
+]
+
+autodoc_member_order = 'groupwise'
+# autodoc_mock_imports allows Sphinx to ignore any external modules listed in the array
 autodoc_mock_imports = []
+
+html_theme_options = {
+    "sticky_navigation": False
+}

gemd/entity/attribute/condition.py

@@ -8,6 +8,24 @@ class Condition(BaseAttribute):
     Conditions are environmental variables (typically measured) that may affect a process
     or measurement: e.g., temperature, pressure.
 
+    Parameters
+    ----------
+    name: str
+        Required name of the attribute. Each attribute within an object must have a unique name.
+    notes: str
+        Optional free-form notes about the attribute.
+    value: :class:`BaseValue <gemd.entity.value.base_value.BaseValue>`
+        The value of the attribute.
+    template: :class:`AttributeTemplate \
+    <gemd.entity.template.attribute_template.AttributeTemplate>`
+        Attribute template that defines the allowed bounds of this attribute. If a template
+        and value are both present then the value must be within the template bounds.
+    origin: str
+        The origin of the attribute. Must be one of "measured", "predicted", "summary",
+        "specified", "computed", or "unknown." Default is "unknown."
+    file_links: List[:class:`FileLink <gemd.entity.file_link.FileLink>`]
+        Links to files associated with the attribute.
+
     """
 
     typ = "condition"

gemd/entity/attribute/parameter.py

@@ -9,6 +9,24 @@ class Parameter(BaseAttribute):
     affect a process or measurement: e.g. oven dial temperature for a kiln firing, magnification
     for a measurement taken with an electron microscope.
 
+    Parameters
+    ----------
+    name: str
+        Required name of the attribute. Each attribute within an object must have a unique name.
+    notes: str
+        Optional free-form notes about the attribute.
+    value: :class:`BaseValue <gemd.entity.value.base_value.BaseValue>`
+        The value of the attribute.
+    template: :class:`AttributeTemplate \
+    <gemd.entity.template.attribute_template.AttributeTemplate>`
+        Attribute template that defines the allowed bounds of this attribute. If a template
+        and value are both present then the value must be within the template bounds.
+    origin: str
+        The origin of the attribute. Must be one of "measured", "predicted", "summary",
+        "specified", "computed", or "unknown." Default is "unknown."
+    file_links: List[:class:`FileLink <gemd.entity.file_link.FileLink>`]
+        Links to files associated with the attribute.
+
     """
 
     typ = "parameter"

gemd/entity/attribute/property.py

@@ -6,7 +6,25 @@ class Property(BaseAttribute):
     Property of a material, measured in a MeasurementRun or specified in a MaterialSpec.
 
     Properties are characteristics of a material that could be measured, e.g. chemical composition,
-     density, yield strength.
+    density, yield strength.
+
+    Parameters
+    ----------
+    name: str
+        Required name of the attribute. Each attribute within an object must have a unique name.
+    notes: str
+        Optional free-form notes about the attribute.
+    value: :class:`BaseValue <gemd.entity.value.base_value.BaseValue>`
+        The value of the attribute.
+    template: :class:`AttributeTemplate \
+    <gemd.entity.template.attribute_template.AttributeTemplate>`
+        Attribute template that defines the allowed bounds of this attribute. If a template
+        and value are both present then the value must be within the template bounds.
+    origin: str
+        The origin of the attribute. Must be one of "measured", "predicted", "summary",
+        "specified", "computed", or "unknown." Default is "unknown."
+    file_links: List[:class:`FileLink <gemd.entity.file_link.FileLink>`]
+        Links to files associated with the attribute.
 
     """
 

gemd/entity/attribute/property_and_conditions.py

@@ -12,9 +12,9 @@ class PropertyAndConditions(DictSerializable):
 
     Parameters
     ----------
-    property: Property
+    property: :class:`Property <gemd.entity.attribute.property.Property>`
         A property attribute
-    conditions: List[Condition]
+    conditions: List[:class:`Condition <gemd.entity.attribute.condition.Condition>`]
         An optional list of conditions associated with this property.
 
     """

gemd/entity/object/base_object.py

@@ -23,7 +23,7 @@ class BaseObject(BaseEntity):
         for filtering and discoverability.
     notes: str, optional
         Long-form notes about the object.
-    file_links: List[FileLink], optional
+    file_links: List[:class:`FileLink <gemd.entity.file_link.FileLink>`], optional
         Links to associated files, with resource paths into the files API.
 
     """

gemd/entity/object/has_conditions.py

@@ -4,7 +4,14 @@
 
 
 class HasConditions(object):
-    """Mixin-trait for entities that include conditions."""
+    """Mixin-trait for entities that include conditions.
+
+    Parameters
+    ----------
+    conditions: List[:class:`Condition <gemd.entity.attribute.condition.Condition>`]
+        A list of conditions associated with this entity.
+
+    """
 
     def __init__(self, conditions):
         self._conditions = None

gemd/entity/object/has_parameters.py

@@ -4,7 +4,14 @@
 
 
 class HasParameters(object):
-    """Mixin-trait for entities that include parameters."""
+    """Mixin-trait for entities that include parameters.
+
+    Parameters
+    ----------
+    parameters: List[:class:`Parameter <gemd.entity.attribute.parameter.Parameter>`]
+        A list of parameters associated with this entity.
+
+    """
 
     def __init__(self, parameters):
         self._parameters = None