Documentation refactoring to use RTD theme

James K. Glasbrenner · James K. Glasbrenner · commit 47518ada8a1e · 2018-08-07T00:49:31.000-04:00
* Adopt RTD theme for docs HTML rendering. * Refactored the settings related to generating the table of contents as this is rendered somewhat differently in the RTD theme. * Update RTD configuration settings, just install requirements in setup.py file instead of using environment.yaml. * Generate individual rst files for all individual functions. * Add CSS file to fix wrapping issues as discussed here, readthedocs/sphinx_rtd_theme#432 (comment). * Revise content on index.rst file.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -4,9 +4,9 @@ build:
 
 python:
   version: 3.6
-
-conda:
-  file: environment.yaml
+  setup_py_install: true
+  extra_requirements:
+    - docs
 
 formats: []
 ...
diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css
@@ -0,0 +1,11 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+  .wy-table-responsive table td {
+    /* !important prevents the common CSS stylesheets from overriding
+     this as on RTD they are loaded after this stylesheet */
+    white-space: normal !important;
+  }
+  .wy-table-responsive {
+    overflow: visible !important;
+  }
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -27,11 +27,6 @@
 # The full version, including alpha/beta/rc tags
 release = '0.0.1'
 
-# -- Autodoc configuration ---------------------------------------------------
-
-autodoc_member_order = "bysource"
-autosummary_generate = True
-
 # -- General configuration ---------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -67,34 +62,50 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+# pygments_style = 'sphinx'
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'nature'
+on_rtd = os.environ.get('READTHEDOCS') == 'True'
+if on_rtd:
+    html_theme = 'default'
+else:
+    html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
 # html_theme_options = {}
 
+html_use_index = False
+
 # 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']
 
+html_context = {
+    'css_files': [
+        '_static/theme_overrides.css',  # override wide tables in RTD theme
+    ],
+}
+
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #
@@ -165,6 +176,11 @@
 
 # -- Extension configuration -------------------------------------------------
 
+# -- Options for autodoc extension -------------------------------------------
+
+autodoc_member_order = "bysource"
+autosummary_generate = True
+
 # -- Options for todo extension ----------------------------------------------
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
diff --git a/docs/index.rst b/docs/index.rst
@@ -8,103 +8,7 @@ neighbormodels documentation
 API
 ===
 
-
-Modules
--------
-
 .. toctree::
+   :maxdepth: 2
 
    modules
-
-
-``interactions``
-^^^^^^^^^^^^^^^^
-
-.. automodule:: neighbormodels.interactions
-
-   .. rubric:: Primary method
-
-   .. autosummary::
-   
-      build_model
-
-   .. rubric:: Functions
-
-   .. autosummary::
-   
-      aggregate_interaction_coefficients
-      build_magnetic_patterns_data_frame
-      compute_interaction_signs
-      compute_model_coefficients
-      group_subspecie_pairs_and_rank_by_distance
-      label_interaction_parameters
-      multiply_interaction_signs_and_neighbor_count
-      spread_parameter_name_column
-
-
-``neighbors``
-^^^^^^^^^^^^^
-
-.. automodule:: neighbormodels.neighbors
-  
-   .. rubric:: Primary method
-
-   .. autosummary::
-   
-      count_neighbors
-
-   .. rubric:: Functions
-
-   .. autosummary::
-   
-      add_subspecie_labels_if_missing
-      append_site_i_neighbor_distance_data
-      count_neighbors_within_distance_groups
-      define_bin_intervals
-      define_bins_to_group_and_sort_by_distance
-      extract_neighbor_distance_data
-      find_unique_distances
-      get_neighbor_distances_data_frame
-      group_site_index_pairs_by_distance
-   
-   .. rubric:: Classes
-
-   .. autosummary::
-   
-      NeighborData
-
-
-``structure``
-^^^^^^^^^^^^^
-
-.. automodule:: neighbormodels.structure
-   
-   .. rubric:: Primary methods
-
-   .. autosummary::
-
-      from_file
-      from_parameters
-
-   .. autosummary::
-   
-   .. rubric:: Functions
-
-   .. autosummary::
-   
-      get_subspecies_labels
-      label_subspecies
-   
-   .. rubric:: Classes
-
-   .. autosummary::
-   
-      StructureParameters
-   
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/modules.rst b/docs/modules.rst
@@ -1,7 +1,9 @@
-neighbormodels
-==============
+Modules
+=======
 
 .. toctree::
    :maxdepth: 4
 
-   neighbormodels
+   neighbormodels.interactions
+   neighbormodels.neighbors
+   neighbormodels.structure
diff --git a/docs/modules/neighbormodels.interactions.aggregate_interaction_coefficients.rst b/docs/modules/neighbormodels.interactions.aggregate_interaction_coefficients.rst
@@ -0,0 +1,6 @@
+neighbormodels.interactions.aggregate\_interaction\_coefficients
+================================================================
+
+.. currentmodule:: neighbormodels.interactions
+
+.. autofunction:: aggregate_interaction_coefficients
diff --git a/docs/modules/neighbormodels.interactions.build_magnetic_patterns_data_frame.rst b/docs/modules/neighbormodels.interactions.build_magnetic_patterns_data_frame.rst
@@ -0,0 +1,6 @@
+neighbormodels.interactions.build\_magnetic\_patterns\_data\_frame
+==================================================================
+
+.. currentmodule:: neighbormodels.interactions
+
+.. autofunction:: build_magnetic_patterns_data_frame
diff --git a/docs/modules/neighbormodels.interactions.build_model.rst b/docs/modules/neighbormodels.interactions.build_model.rst
@@ -0,0 +1,6 @@
+neighbormodels.interactions.build\_model
+========================================
+
+.. currentmodule:: neighbormodels.interactions
+
+.. autofunction:: build_model
diff --git a/docs/modules/neighbormodels.interactions.compute_interaction_signs.rst b/docs/modules/neighbormodels.interactions.compute_interaction_signs.rst
@@ -0,0 +1,6 @@
+neighbormodels.interactions.compute\_interaction\_signs
+=======================================================
+
+.. currentmodule:: neighbormodels.interactions
+
+.. autofunction:: compute_interaction_signs
diff --git a/docs/modules/neighbormodels.interactions.compute_model_coefficients.rst b/docs/modules/neighbormodels.interactions.compute_model_coefficients.rst
@@ -0,0 +1,6 @@
+neighbormodels.interactions.compute\_model\_coefficients
+========================================================
+
+.. currentmodule:: neighbormodels.interactions
+
+.. autofunction:: compute_model_coefficients
diff --git a/docs/modules/neighbormodels.interactions.group_subspecie_pairs_and_rank_by_distance.rst b/docs/modules/neighbormodels.interactions.group_subspecie_pairs_and_rank_by_distance.rst
@@ -0,0 +1,6 @@
+neighbormodels.interactions.group\_subspecie\_pairs\_and\_rank\_by\_distance
+============================================================================
+
+.. currentmodule:: neighbormodels.interactions
+
+.. autofunction:: group_subspecie_pairs_and_rank_by_distance
diff --git a/docs/modules/neighbormodels.interactions.label_interaction_parameters.rst b/docs/modules/neighbormodels.interactions.label_interaction_parameters.rst
@@ -0,0 +1,6 @@
+neighbormodels.interactions.label\_interaction\_parameters
+==========================================================
+
+.. currentmodule:: neighbormodels.interactions
+
+.. autofunction:: label_interaction_parameters
diff --git a/docs/modules/neighbormodels.interactions.multiply_interaction_signs_and_neighbor_count.rst b/docs/modules/neighbormodels.interactions.multiply_interaction_signs_and_neighbor_count.rst
@@ -0,0 +1,6 @@
+neighbormodels.interactions.multiply\_interaction\_signs\_and\_neighbor\_count
+==============================================================================
+
+.. currentmodule:: neighbormodels.interactions
+
+.. autofunction:: multiply_interaction_signs_and_neighbor_count
diff --git a/docs/modules/neighbormodels.interactions.spread_parameter_name_column.rst b/docs/modules/neighbormodels.interactions.spread_parameter_name_column.rst
@@ -0,0 +1,6 @@
+neighbormodels.interactions.spread\_parameter\_name\_column
+===========================================================
+
+.. currentmodule:: neighbormodels.interactions
+
+.. autofunction:: spread_parameter_name_column
diff --git a/docs/modules/neighbormodels.neighbors.NeighborData.rst b/docs/modules/neighbormodels.neighbors.NeighborData.rst
@@ -0,0 +1,31 @@
+neighbormodels.neighbors.NeighborData
+=====================================
+
+.. currentmodule:: neighbormodels.neighbors
+
+.. autoclass:: NeighborData
+
+   
+   .. automethod:: __init__
+
+   
+   .. rubric:: Methods
+
+   .. autosummary::
+   
+      ~NeighborData.count
+      ~NeighborData.index
+   
+   
+
+   
+   
+   .. rubric:: Attributes
+
+   .. autosummary::
+   
+      ~NeighborData.bins_data_frame
+      ~NeighborData.data_frame
+      ~NeighborData.structure
+   
+   
diff --git a/docs/modules/neighbormodels.neighbors.add_subspecie_labels_if_missing.rst b/docs/modules/neighbormodels.neighbors.add_subspecie_labels_if_missing.rst
@@ -0,0 +1,6 @@
+neighbormodels.neighbors.add\_subspecie\_labels\_if\_missing
+============================================================
+
+.. currentmodule:: neighbormodels.neighbors
+
+.. autofunction:: add_subspecie_labels_if_missing
diff --git a/docs/modules/neighbormodels.neighbors.append_site_i_neighbor_distance_data.rst b/docs/modules/neighbormodels.neighbors.append_site_i_neighbor_distance_data.rst
@@ -0,0 +1,6 @@
+neighbormodels.neighbors.append\_site\_i\_neighbor\_distance\_data
+==================================================================
+
+.. currentmodule:: neighbormodels.neighbors
+
+.. autofunction:: append_site_i_neighbor_distance_data
diff --git a/docs/modules/neighbormodels.neighbors.count_neighbors.rst b/docs/modules/neighbormodels.neighbors.count_neighbors.rst
@@ -0,0 +1,6 @@
+neighbormodels.neighbors.count\_neighbors
+=========================================
+
+.. currentmodule:: neighbormodels.neighbors
+
+.. autofunction:: count_neighbors
diff --git a/docs/modules/neighbormodels.neighbors.count_neighbors_within_distance_groups.rst b/docs/modules/neighbormodels.neighbors.count_neighbors_within_distance_groups.rst
@@ -0,0 +1,6 @@
+neighbormodels.neighbors.count\_neighbors\_within\_distance\_groups
+===================================================================
+
+.. currentmodule:: neighbormodels.neighbors
+
+.. autofunction:: count_neighbors_within_distance_groups
diff --git a/docs/modules/neighbormodels.neighbors.define_bin_intervals.rst b/docs/modules/neighbormodels.neighbors.define_bin_intervals.rst
@@ -0,0 +1,6 @@
+neighbormodels.neighbors.define\_bin\_intervals
+===============================================
+
+.. currentmodule:: neighbormodels.neighbors
+
+.. autofunction:: define_bin_intervals
diff --git a/docs/modules/neighbormodels.neighbors.define_bins_to_group_and_sort_by_distance.rst b/docs/modules/neighbormodels.neighbors.define_bins_to_group_and_sort_by_distance.rst
@@ -0,0 +1,6 @@
+neighbormodels.neighbors.define\_bins\_to\_group\_and\_sort\_by\_distance
+=========================================================================
+
+.. currentmodule:: neighbormodels.neighbors
+
+.. autofunction:: define_bins_to_group_and_sort_by_distance
diff --git a/docs/modules/neighbormodels.neighbors.extract_neighbor_distance_data.rst b/docs/modules/neighbormodels.neighbors.extract_neighbor_distance_data.rst
@@ -0,0 +1,6 @@
+neighbormodels.neighbors.extract\_neighbor\_distance\_data
+==========================================================
+
+.. currentmodule:: neighbormodels.neighbors
+
+.. autofunction:: extract_neighbor_distance_data
diff --git a/docs/modules/neighbormodels.neighbors.find_unique_distances.rst b/docs/modules/neighbormodels.neighbors.find_unique_distances.rst
@@ -0,0 +1,6 @@
+neighbormodels.neighbors.find\_unique\_distances
+================================================
+
+.. currentmodule:: neighbormodels.neighbors
+
+.. autofunction:: find_unique_distances
diff --git a/docs/modules/neighbormodels.neighbors.get_neighbor_distances_data_frame.rst b/docs/modules/neighbormodels.neighbors.get_neighbor_distances_data_frame.rst
@@ -0,0 +1,6 @@
+neighbormodels.neighbors.get\_neighbor\_distances\_data\_frame
+==============================================================
+
+.. currentmodule:: neighbormodels.neighbors
+
+.. autofunction:: get_neighbor_distances_data_frame
diff --git a/docs/modules/neighbormodels.neighbors.group_site_index_pairs_by_distance.rst b/docs/modules/neighbormodels.neighbors.group_site_index_pairs_by_distance.rst
diff --git a/docs/modules/neighbormodels.structure.StructureParameters.rst b/docs/modules/neighbormodels.structure.StructureParameters.rst
diff --git a/docs/modules/neighbormodels.structure.from_file.rst b/docs/modules/neighbormodels.structure.from_file.rst
diff --git a/docs/modules/neighbormodels.structure.from_parameters.rst b/docs/modules/neighbormodels.structure.from_parameters.rst
diff --git a/docs/modules/neighbormodels.structure.get_subspecies_labels.rst b/docs/modules/neighbormodels.structure.get_subspecies_labels.rst
diff --git a/docs/modules/neighbormodels.structure.label_subspecies.rst b/docs/modules/neighbormodels.structure.label_subspecies.rst
diff --git a/docs/neighbormodels.interactions.rst b/docs/neighbormodels.interactions.rst
diff --git a/docs/neighbormodels.neighbors.rst b/docs/neighbormodels.neighbors.rst
diff --git a/docs/neighbormodels.rst b/docs/neighbormodels.rst
diff --git a/docs/neighbormodels.structure.rst b/docs/neighbormodels.structure.rst
diff --git a/environment.yaml b/environment.yaml
diff --git a/setup.py b/setup.py
