Use numpydoc for docstrings

Author: has2k1

doc/_static/custom.css

@@ -90,3 +90,21 @@ table.dataframe thead th {
 table.dataframe tbody tr:nth-child(odd) {
    background: #F0F6F6;
 }
+
+
+/* Aesthetics table */
+
+table.field-list dd table>tbody>tr>td,
+table.field-list dd table>tbody>tr>th,
+table.field-list dd table>tfoot>tr>td,
+table.field-list dd table>tfoot>tr>th,
+table.field-list dd table>thead>tr>td,
+table.field-list dd table>thead>tr>th {
+    padding: 0.5em;
+}
+
+/* Computed aesthetics */
+
+.content table.field-list dd>p.rubric {
+    margin: 1.5em 0 1em;
+}

doc/conf.py

@@ -53,12 +53,12 @@
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.autosummary',
-    'sphinx.ext.napoleon',
 
     'sphinxext.examples_and_gallery',
     'sphinxext.inline_code_highlight',
 
-    'nbsphinx'
+    'nbsphinx',
+    'numpydoc',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -410,6 +410,34 @@
 }
 
 
+numpydoc_show_class_members = False
+numpydoc_class_members_toctree = False
+numpydoc_xref_param_type = True
+numpydoc_xref_aliases = {
+    # python
+    'sequence': ':term:`python:sequence`',
+    'iterable': ':term:`python:iterable`',
+    'string': 'str',
+    'tuples': 'tuple',
+    'boolean': 'bool',
+    # numpy
+    'array': 'numpy.ndarray',
+    'np.array': 'numpy.ndarray',
+    'ndarray': 'numpy.ndarray',
+    'array-like': ':term:`array-like<numpy:array_like>`',
+    'array_like': ':term:`numpy:array_like`',
+    # pandas
+    'dataframe': 'pandas.DataFrame',
+    'DataFrame': 'pandas.DataFrame',
+    'Series': 'pandas.Series',
+    'series': 'pandas.Series',
+    # plotnine
+    'geom': ':term:`geom`',
+    'stat': ':term:`stat`',
+    'position': ':term:`position`',
+}
+
+
 def link_to_tutorials():
     # Linking to the directory does not work well with
     # nbsphinx. We link to the files themselves

doc/glossary.rst

@@ -0,0 +1,17 @@
+.. currentmodule:: plotnine
+
+.. _glossary:
+
+Glossary of Common Terms
+========================
+
+.. glossary::
+
+    stat
+        A subclass of :class:`~plotnine.stats.stat.stat`.
+
+    geom
+        A subclass of :class:`~plotnine.geoms.geom.geom`.
+
+    position
+        A subclass of :class:`~plotnine.positions.position.position`.

doc/index.rst

@@ -39,6 +39,7 @@ Documentation
    changelog
    about-plotnine
    tutorials
+   glossary
    external-resources
 
 .. _ggplot2: http://ggplot2.org

doc/theme/layout.html

@@ -1,7 +1,7 @@
 {% extends "basic/layout.html" %}
 
 {% if theme_bootstrap_version == "3" %}
-  {% set bootstrap_version, navbar_version = "3.3.6", "" %}
+  {% set bootstrap_version, navbar_version = "3.3.7", "" %}
   {% set bs_span_prefix = "col-md-" %}
 {% else %}
   {% set bootstrap_version, navbar_version = "2.3.2", "-2" %}

doc/theme/static/bootstrap-3.3.6/css/bootstrap.min.css

@@ -9,33 +9,25 @@
  * Imports to aggregate everything together.
  */
 
-@import url("basic.css");
+@import url("./basic.css");
 
 {% if theme_bootstrap_version == "3" %}
-  {% set bootstrap_version, bootstrap_additional_css = "3.3.6", "theme" %}
-  {% set bs_span_prefix = "col-md-" %}
+  {% set bootstrap_version, bootstrap_additional_css = "3.3.7", "theme" %}
 {% else %}
   {% set bootstrap_version, bootstrap_additional_css = "2.3.2", "responsive" %}
-  {% set bs_span_prefix = "span" %}
 {% endif %}
 
 {% if theme_bootswatch_theme and theme_bootswatch_theme != "\"\"" %}
   {# BS2 needs "bootstrap-responsive.css". BS3 doesn't. #}
   {% if theme_bootstrap_version == "3" %}
-    @import url("{{ 'bootswatch-' + bootstrap_version + '/' + theme_bootswatch_theme + '/bootstrap.min.css' }}");
+    @import url("{{ './bootswatch-' + bootstrap_version + '/' + theme_bootswatch_theme + '/bootstrap.min.css' }}");
   {% else %}
-    @import url("{{ 'bootswatch-' + bootstrap_version + '/' + theme_bootswatch_theme + '/bootstrap.min.css' }}");
-    @import url("{{ 'bootstrap-' + bootstrap_version + '/css/bootstrap-' + bootstrap_additional_css + '.min.css' }}");
+    @import url("{{ './bootswatch-' + bootstrap_version + '/' + theme_bootswatch_theme + '/bootstrap.min.css' }}");
+    @import url("{{ './bootstrap-' + bootstrap_version + '/css/bootstrap-' + bootstrap_additional_css + '.min.css' }}");
   {% endif %}
 {% else %}
-    @import url("{{ 'bootstrap-' + bootstrap_version + '/css/bootstrap.min.css' }}");
-    @import url("{{ 'bootstrap-' + bootstrap_version + '/css/bootstrap-' + bootstrap_additional_css + '.min.css' }}");
-{% endif %}
-
-{% if bootswatch_css_custom %}
-  {%- for css_custom in bootswatch_css_custom %}
-    @import url("{{ css_custom }}");
-  {%- endfor %}
+    @import url("{{ './bootstrap-' + bootstrap_version + '/css/bootstrap.min.css' }}");
+    @import url("{{ './bootstrap-' + bootstrap_version + '/css/bootstrap-' + bootstrap_additional_css + '.min.css' }}");
 {% endif %}
 
 /*
@@ -125,6 +117,10 @@ div.highlight {
   background: none;
 }
 
+a.headerlink {
+  margin-left: 0.25em;
+}
+
 a.footnote-reference {
   vertical-align: super;
   font-size: 75%;

doc/theme/static/bootstrap-3.3.6/js/bootstrap.min.js

@@ -97,7 +97,7 @@
 
       // Enlarge content if sidebar is larger.
       if ($sideBar.outerHeight(true) > $content.outerHeight(true)) {
-        $content.minHeight($sideBar.outerHeight(true));
+        $content.css("min-height", $sideBar.outerHeight(true));
       }
 
       $sideBar

doc/theme/static/bootstrap-3.3.7/css/bootstrap.min.css

@@ -53,7 +53,7 @@ source_link_position = nav
 # Bootswatch (http://bootswatch.com/) theme.
 #
 # Options are nothing (default) or the name of a valid theme such as
-# "amelia" or "cosmo".
+# "cosmo" or "sandstone".
 bootswatch_theme =
 
 # Switch Bootstrap version?

doc/theme/static/bootstrap-3.3.7/js/bootstrap.min.js

@@ -36,12 +36,15 @@ class aes(dict):
         x aesthetic mapping
     y : str | array_like | scalar | str-expression
         y aesthetic mapping
-
-    **kwargs : dict
+    \*\*kwargs : dict
         Other aesthetic mappings
 
+    Notes
+    -----
+    Only the **x** and **y** aesthetic mappings can be specified as
+    positional arguments. All the rest must be keyword arguments.
 
-    The value of each mapping must be one of;
+    The value of each mapping must be one of:
 
     - **string**::
 
@@ -111,10 +114,6 @@ class aes(dict):
     groups are sufficient. However, there may be cases were it is
     handy to map to it.
 
-    Note
-    ----
-    Only the **x** and **y** aesthetic mappings can be specified as
-    positional arguments. All the rest must be keyword arguments.
     """
 
     def __init__(self, *args, **kwargs):
@@ -363,8 +362,8 @@ def is_valid_aesthetic(value, ae):
     out : bool
         Whether the value is of a valid looking form.
 
-    Note
-    ----
+    Notes
+    -----
     There are no guarantees that he value is spot on
     valid.
     """

doc/theme/static/bootstrap-sphinx.css_t

@@ -26,8 +26,8 @@ class PlotnineAnimation(ArtistAnimation):
         Controls whether blitting is used to optimize drawing. Defaults
         to `False`.
 
-    Note
-    ----
+    Notes
+    -----
     1. The plots should have the same `facet` and
        the facet should not have fixed x and y scales.
     2. The scales of all the plots should have the same limits. It is

doc/theme/static/bootstrap-sphinx.js_t

@@ -68,8 +68,8 @@ def setup_layout(self, layout):
             layout dataframe altered to according to the requirements
             of the coordinate system.
 
-        Note
-        ----
+        Notes
+        -----
         The input dataframe may be changed.
         """
         return layout

doc/theme/theme.conf

@@ -23,8 +23,8 @@ class coord_fixed(coord_cartesian):
         some factor. If `False`, use the limits
         from the data.
 
-    Note
-    ----
+    Notes
+    -----
     To specify aspect ratio of the visual size for the axes use the
     :class:`~plotnine.themes.themeable.aspect_ratio` themeable::