fix(docs): Add several documentation fixes for correct display

* docs(package): Fix docstrings for proper display of documentation - Issue #158 - Improved docstring contents - Make docstring format of classes and methods sphinx friendly - First pass, issues remain - see PR comments for more info. * docs(conf.py): Additional configurations/post-processing functions added - #Issue 158 New from ladybug.geometry version: Added make_properties_one_liner function to solve multiline property descriptions issue. See PR comments for more info. * chore(bootstrap sidebar): Adding custom template files to fix sidebar - Issue #158 As implemented in ladybug.geoemtry package * docs(package): Update docstrings for proper display - Changed to_dict() dictionary descritpions to python syntax - Removed descriptions from class 'Properties' section - Chaged 'Usage' code-block type to python - Changeed FIELDS constant to _fields - Misc. changes to remove warnings from Sphinx build * docs(conf.py): Remove post-processing functions Given that class properties descriptions have been removed autodoc-process-docstring methods are unnecesary. * fix(EPWFields): Rename constant to match new name (FIELDS with _fields) * doc(DataTypeBase): Improve properties' docstring * fix(conf.py): Regex library not used - import removed * doc(DataTypeBase): Improve properties' docstring - second pass * docs(package): Fix dictionary values in to_dict() docstrings * docs(package): Fix docstrings following detailed review * docs(setup): Fix docstring type * docs(package): Fix docstrings to avoid Sphinx warnings at build * docs(package): Fix docstrings following second review
ladybug-tools · Oct 14, 2019 · b2d518b · b2d518b
1 parent edbd970
commit b2d518b
Show file tree

Hide file tree

Showing 47 changed files with 1,634 additions and 1,006 deletions.
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -0,0 +1,40 @@
+/*
+ * bootstrap-sphinx.css
+ * ~~~~~~~~~~~~~~~~~~~~
+ *
+ * Sphinx stylesheet -- Bootstrap theme.
+ */
+
+
+/* The code below is based on the bootstrap website sidebar */
+
+
+/* Show and affix the side nav when space allows it */
+@media screen and (min-width: 992px) {
+ .bs-sidenav .nav > .active > ul {
+ display: block;
+ }
+ /* Widen the fixed sidenav */
+ .bs-sidenav.affix,
+ .bs-sidenav.affix-bottom {
+ width: 292px;
+ }
+ .bs-sidenav.affix {
+ position: fixed; /* Undo the static from mobile first approach */
+ }
+ .bs-sidenav.affix-bottom {
+ position: absolute; /* Undo the static from mobile first approach */
+ }
+ .bs-sidenav.affix-bottom .bs-sidenav,
+ .bs-sidenav.affix .bs-sidenav {
+ margin-top: 0;
+ margin-bottom: 0;
+ }
+}
+@media screen and (min-width: 1200px) {
+ /* Widen the fixed sidenav again */
+ .bs-sidenav.affix-bottom,
+ .bs-sidenav.affix {
+ width: 360px;
+ }
+}
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
@@ -0,0 +1,107 @@
+{% extends "basic/layout.html" %}
+
+{% if theme_bootstrap_version == "3" %}
+ {% set bootstrap_version, navbar_version = "3.3.7", "" %}
+ {% set bs_span_prefix = "col-md-" %}
+{% else %}
+ {% set bootstrap_version, navbar_version = "2.3.2", "-2" %}
+ {% set bs_span_prefix = "span" %}
+{% endif %}
+
+{%- set render_sidebar = (not embedded) and (not theme_nosidebar|tobool) and sidebars %}
+
+{%- set bs_content_width = render_sidebar and "8" or "12"%}
+
+{%- block doctype -%}
+<!DOCTYPE html>
+{%- endblock %}
+
+{# Sidebar: Rework into our Bootstrap nav section. #}
+{% macro navBar() %}
+{% include "navbar" + navbar_version + ".html" %}
+{% endmacro %}
+
+{% if theme_bootstrap_version == "3" %}
+ {%- macro bsidebar() %}
+ {%- if render_sidebar %}
+ <div class="{{ bs_span_prefix }}4">
+ <div id="sidebar" class="bs-sidenav" role="complementary">
+ {%- for sidebartemplate in sidebars %}
+ {%- include sidebartemplate %}
+ {%- endfor %}
+ </div>
+ </div>
+ {%- endif %}
+ {%- endmacro %}
+{% else %}
+ {%- macro bsidebar() %}
+ {%- if render_sidebar %}
+ <div class="{{ bs_span_prefix }}4">
+ <div id="sidebar" class="bs-sidenav well" data-spy="affix">
+ {%- for sidebartemplate in sidebars %}
+ {%- include sidebartemplate %}
+ {%- endfor %}
+ </div>
+ </div>
+ {%- endif %}
+ {%- endmacro %}
+{% endif %}
+
+{%- block extrahead %}
+<meta charset='utf-8'>
+<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
+<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
+<meta name="apple-mobile-web-app-capable" content="yes">
+<script type="text/javascript" src="{{ pathto('_static/js/jquery-1.11.0.min.js', 1) }} "></script>
+<script type="text/javascript" src="{{ pathto('_static/js/jquery-fix.js', 1) }} "></script>
+<script type="text/javascript" src="{{ pathto('_static', 1) + '/bootstrap-' + bootstrap_version + '/js/bootstrap.min.js' }} "></script>
+<script type="text/javascript" src="{{ pathto('_static/bootstrap-sphinx.js', 1) }} "></script>
+{% endblock %}
+
+{# Silence the sidebar's, relbar's #}
+{% block header %}{% endblock %}
+{% block relbar1 %}{% endblock %}
+{% block relbar2 %}{% endblock %}
+{% block sidebarsourcelink %}{% endblock %}
+
+{%- block content %}
+{{ navBar() }}
+<div class="container">
+ <div class="row">
+ {%- block sidebar1 %}{{ bsidebar() }}{% endblock %}
+ <div class="body {{ bs_span_prefix }}{{ bs_content_width }} content" role="main">
+ {% block body %}{% endblock %}
+ </div>
+ {% block sidebar2 %} {# possible location for sidebar #} {% endblock %}
+ </div>
+</div>
+{%- endblock %}
+
+{%- block footer %}
+<footer class="footer">
+ <div class="container">
+ <p class="pull-right">
+ <a href="#">Back to top</a>
+ {% if theme_source_link_position == "footer" %}
+ <br/>
+ {% include "sourcelink.html" %}
+ {% endif %}
+ </p>
+ <p>
+ {%- if show_copyright %}
+ {%- if hasdoc('copyright') %}
+ {% trans path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}<br/>
+ {%- else %}
+ {% trans copyright=copyright|e %}&copy; Copyright {{ copyright }}.{% endtrans %}<br/>
+ {%- endif %}
+ {%- endif %}
+ {%- if last_updated %}
+ {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}<br/>
+ {%- endif %}
+ {%- if show_sphinx %}
+ {% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}<br/>
+ {%- endif %}
+ </p>
+ </div>
+</footer>
+{%- endblock %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -100,11 +100,11 @@
  # Fix navigation bar to top of page?
  # Values: "true" (default) or "false"
  'navbar_fixed_top': "true",
- 'navbar_pagenav': True,
+ 'navbar_pagenav': True,
  'source_link_position': "nav",
- 'bootswatch_theme': "united",
+ 'bootswatch_theme': "united",
  'bootstrap_version': "3",
- }
+}
 
 # on_rtd is whether we are on readthedocs.org
 # on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
@@ -213,3 +213,21 @@
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
+
+# -- Options for autodoc extension --------------------------------------------
+autodoc_default_options = {
+ 'inherited-members': True,
+}
+
+autodoc_member_order = 'groupwise'
+
+
+def setup(app):
+ """Run custom code with access to the Sphinx application object
+
+ Args:
+ app: the Sphinx application object
+ """
+
+ # Add bootstrap theme custom stylesheet
+ app.add_stylesheet("custom.css")
diff --git a/ladybug/_datacollectionbase.py b/ladybug/_datacollectionbase.py
@@ -18,7 +18,14 @@
 
 
 class BaseCollection(object):
- """Base class for all Data Collections."""
+ """Base class for all Data Collections.
+
+ Args:
+ header: A Ladybug Header object.
+ values: A list of values.
+ datetimes: A list of Ladybug DateTime objects that aligns with
+ the list of values.
+ """
 
  __slots__ = ('_header', '_values', '_datetimes', '_validated_a_period')
  _collection_type = None
@@ -27,12 +34,6 @@ class BaseCollection(object):
 
  def __init__(self, header, values, datetimes):
  """Initialize base collection.
-
- Args:
- header: A Ladybug Header object.
- values: A list of values.
- datetimes: A list of Ladybug DateTime objects that aligns with
- the list of values.
  """
  assert isinstance(header, Header), \
  'header must be a Ladybug Header object. Got {}'.format(type(header))
@@ -50,11 +51,16 @@ def from_dict(cls, data):
  """Create a Data Collection from a dictionary.
 
  Args:
+ data: A python dictionary in the following format
+
+ .. code-block:: python
+
  {
- "header": A Ladybug Header,
- "values": An array of values,
- "datetimes": An array of datetimes,
- "validated_a_period": Boolean for whether header analysis_period is valid
+ "header": {}, # A Ladybug Header
+ "values": [], # An array of values
+ "datetimes": [], # An array of datetimes
+ "validated_a_period": True # Boolean for whether header analysis_period
+ # is valid
  }
  """
  assert 'header' in data, 'Required keyword "header" is missing!'
@@ -189,9 +195,14 @@ def get_highest_values(self, count):
  count: Integer representing the number of highest values to account for.
 
  Returns:
- highest_values: The n highest values in data list, ordered from
+ A tuple with two elements.
+
+ - highest_values:
+ The n highest values in data list, ordered from
  highest to lowest.
- highest_values_index: Indicies of the n highest values in data
+
+ - highest_values_index:
+ Indicies of the n highest values in data
  list, ordered from highest to lowest.
  """
  count = int(count)
@@ -216,9 +227,13 @@ def get_lowest_values(self, count):
  count: Integer representing the number of lowest values to account for.
 
  Returns:
- highest_values: The n lowest values in data list, ordered from
+ A tuple with two elements.
+
+ - highest_values:
+ The n lowest values in data list, ordered from
  lowest to lowest.
- lowest_values_index: Indicies of the n lowest values in data
+ - lowest_values_index:
+ Indicies of the n lowest values in data
  list, ordered from lowest to lowest.
  """
  count = int(count)
@@ -376,8 +391,8 @@ def filter_collections_by_statement(data_collections, statement):
  The variable should always be named as 'a' (without quotations).
 
  Return:
- collections: A list of Data Collections that have been filtered based
-  on the statement.
+ collections -- A list of Data Collections that have been filtered based
+ on the statement.
  """
  pattern = BaseCollection.pattern_from_collections_and_statement(
  data_collections, statement)
@@ -399,9 +414,9 @@ def pattern_from_collections_and_statement(data_collections, statement):
  The variable should always be named as 'a' (without quotations).
 
  Return:
- pattern: A list of True/False booleans with the length of the
-  Data Collections where True meets the conditional statement
-  and False does not.
+ pattern -- A list of True/False booleans with the length of the
+ Data Collections where True meets the conditional statement
+ and False does not.
  """
  BaseCollection.are_collections_aligned(data_collections)
  correct_var = BaseCollection._check_conditional_statement(
@@ -468,6 +483,9 @@ def compute_function_aligned(funct, data_collections, data_type, unit):
  data_collections are individual values, only a single value will be returned.
 
  Usage:
+
+ .. code-block:: python
+
  from ladybug.datacollection import HourlyContinuousCollection
  from ladybug.epw import EPW
  from ladybug.psychrometrics import humid_ratio_from_db_rh
@@ -519,7 +537,7 @@ def _check_conditional_statement(statement, num_collections):
  that the statement will be evaluating.
 
  Return:
- correct_var: A list of the correct variable names that should be
+ correct_var -- A list of the correct variable names that should be
  used within the statement (eg. ['a', 'b', 'c'])
  """
  # Determine what the list of variables should be based on the num_collections