Merge additional pydocstyle error fixes into development docs (#1208)

* Fix _fh.py docstrings * Remove __init_ from class_with_call doc template * Update api reference files .rst files * Tweak docstrings * more pydocstyle docs fixes * Update doc python object templates * Switch to numpydoc extension and pydata theme * Update doc requirements * Remove autosummary * Change docstring example to examples * Classification doc tweaks * Series transformer docstring tweaks * Change State docstring heading moved to notes * Annotation docstring tweaks * Tweak dataset docstrings * Additional docstring tweak * add twitter and discord icons * add edit-this-page button * remove estimator from init * More docstring tweaks based on numpydoc warnings * More numpydoc warning fixes * Add validation checks when building docs with numpydoc * Restructuring content * remove estimator table since it's auto-generated * Add getting started doc page * Fix annotation pydocstyle errors * Add module docstring in _meta.py * Fix pydocstyle errors in _rise.py * Fix pydocstyle errors in datasets * Fix pydocstyle error in regression/__init__.py * Fix pydocstyle errors in regression module * Fix pydocstyle errors in registry * Fix pydocstyle errors in performance_metrics * Fix series_as_features ensemble pydocstyle errors * Fix pydocstyle errors in forecasting base * Tweak language in performance_metrics docs * More pydocstyle error fixes in forecasting module * Still more pydocstyle error fixes in forecasting * Fix pydocstyle errors in forecasting model_evaluation * Forecasting adapter pydocstyle error fixes * Streamline getting started and fix code blocks * Add autodoc option to order members by source code * Update quickstart Co-authored-by: mloning <markus.loning.17@ucl.ac.uk> Co-authored-by: Markus Löning <markus.loning@gmail.com>
sktime · Jul 28, 2021 · 93b06e0 · 93b06e0
1 parent e576a51
commit 93b06e0
Show file tree

Hide file tree

Showing 48 changed files with 375 additions and 184 deletions.
diff --git a/docs/source/api_reference/performance_metrics.rst b/docs/source/api_reference/performance_metrics.rst
@@ -14,8 +14,8 @@ Forecasting
 
 .. currentmodule:: sktime.performance_metrics.forecasting
 
-Tunable Classes
-~~~~~~~~~~~~~~~
+Classes
+~~~~~~~
 
 .. autosummary::
     :toctree: modules/auto_generated/

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -97,7 +97,17 @@
 
 # generate autosummary even if no references
 autosummary_generate = True
-autodoc_default_options = {"members": True, "inherited-members": True}
+
+# members and inherited-members default to showing methods/attributes, etc
+# from a class that are created in the class or inherited
+# member-order says to order the documentation in the order the members
+# were defined in the source code
+autodoc_default_options = {
+    "members": True,
+    "inherited-members": True,
+    "member-order": "bysource",
+}
+
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = False
 

diff --git a/docs/source/get_involved.rst b/docs/source/get_involved.rst
@@ -0,0 +1,14 @@
+.. _get_involved:
+
+Get involved
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   contributing
+   developer_guide
+   mentoring
+   roadmap
+   code_of_conduct
+   governance
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -13,31 +13,31 @@ Installation
 * environments with python version 3.6, 3.7, or 3.8.
 * operating systems Mac OS X, Unix-like OS, Windows 8.1 and higher
 
-We appreciate community contributions towards compatibility with python 3.9, or other operating systems.
 
+``sktime`` releases are available via ``PyPI`` and ``conda`` .
 
-``sktime`` releases are available via PyPI and you can install ``sktime`` with its core dependencies via ``pip`` using:
+To install ``sktime`` with its core dependencies via ``pip`` use:
 
 .. code-block:: bash
 
     pip install sktime
 
-To install ``sktime`` with maximum dependencies, including soft dependencies, install with the ``all_extras`` modifier:
+To install ``sktime`` via ``pip`` with maximum dependencies, including soft dependencies, install using the ``all_extras`` modifier:
 
 .. code-block:: bash
 
     pip install sktime[all_extras]
 
 
-``sktime`` releases are also available via ``conda`` from ``conda-forge`` and can be installed using:
+To install ``sktime`` via ``conda`` from ``conda-forge`` use:
 
 .. code-block:: bash
 
     conda install -c conda-forge sktime
 
 This will install ``sktime`` with core dependencies, excluding soft dependencies.
 
-Currently, there is no easy route to install ``sktime`` with maximum dependencies via ``conda``. Community contributions towards this, e.g., via conda metapackages, would be appreciated.
+There is not currently a easy route to install ``sktime`` with maximum dependencies via ``conda``. Community contributions towards this, e.g., via conda metapackages, would be appreciated.
 
 For more detailed installation instructions see our more detailed `installation`_ instructions.
 
@@ -52,45 +52,45 @@ For more information on the terminology used by ``sktime`` see INSERT LINK TO OU
 
 Quickstart
 ----------
-The code snippets below are designed to introduce ``sktime's`` functionality so you can start using its functionality quickly. For more detailed information see the `tutorials`_, `user_guide`_ and `api_reference`_ in ``sktime's`` `user_documentation`_.
+The code snippets below are designed to introduce ``sktime's`` functionality so you can start using its functionality quickly. For more detailed information see the :ref:`tutorials`,  :ref:`user_guide` and :ref:`api_reference` in ``sktime's`` :ref:`user_documentation`.
 
 Forecasting
 ~~~~~~~~~~~
 
-```python
-from sktime.datasets import load_airline
-from sktime.forecasting.base import ForecastingHorizon
-from sktime.forecasting.model_selection import temporal_train_test_split
-from sktime.forecasting.theta import ThetaForecaster
-from sktime.performance_metrics.forecasting import mean_absolute_percentage_error
-
-y = load_airline()
-y_train, y_test = temporal_train_test_split(y)
-fh = ForecastingHorizon(y_test.index, is_relative=False)
-forecaster = ThetaForecaster(sp=12)  # monthly seasonal periodicity
-forecaster.fit(y_train)
-y_pred = forecaster.predict(fh)
-mean_absolute_percentage_error(y_test, y_pred)
->>> 0.08661467738190656
-```
+.. code-block:: python
+
+    from sktime.datasets import load_airline
+    from sktime.forecasting.base import ForecastingHorizon
+    from sktime.forecasting.model_selection import temporal_train_test_split
+    from sktime.forecasting.theta import ThetaForecaster
+    from sktime.performance_metrics.forecasting import mean_absolute_percentage_error
+
+    y = load_airline()
+    y_train, y_test = temporal_train_test_split(y)
+    fh = ForecastingHorizon(y_test.index, is_relative=False)
+    forecaster = ThetaForecaster(sp=12)  # monthly seasonal periodicity
+    forecaster.fit(y_train)
+    y_pred = forecaster.predict(fh)
+    mean_absolute_percentage_error(y_test, y_pred)
+    >>> 0.08661467738190656
 
 Time Series Classification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-```python
-from sktime.classification.interval_based import TimeSeriesForestClassifier
-from sktime.datasets import load_arrow_head
-from sklearn.model_selection import train_test_split
-from sklearn.metrics import accuracy_score
-
-X, y = load_arrow_head(return_X_y=True)
-X_train, X_test, y_train, y_test = train_test_split(X, y)
-classifier = TimeSeriesForestClassifier()
-classifier.fit(X_train, y_train)
-y_pred = classifier.predict(X_test)
-accuracy_score(y_test, y_pred)
->>> 0.8679245283018868
-```
+.. code-block:: python
+
+    from sktime.classification.interval_based import TimeSeriesForestClassifier
+    from sktime.datasets import load_arrow_head
+    from sklearn.model_selection import train_test_split
+    from sklearn.metrics import accuracy_score
+
+    X, y = load_arrow_head(return_X_y=True)
+    X_train, X_test, y_train, y_test = train_test_split(X, y)
+    classifier = TimeSeriesForestClassifier()
+    classifier.fit(X_train, y_train)
+    y_pred = classifier.predict(X_test)
+    accuracy_score(y_test, y_pred)
+    >>> 0.8679245283018868
 
 Time Series Clustering
 ~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -13,6 +13,6 @@ From here, you can navigate to:
    :maxdepth: 1
 
    getting_started
-   users
-   developers
+   user_documentation
+   get_involved
    about
diff --git a/docs/source/user_documentation.rst b/docs/source/user_documentation.rst
@@ -0,0 +1,16 @@
+.. _user_documentation:
+
+User Documentation
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   installation
+   tutorials
+   user_guide
+   estimator_overview
+   api_reference
+   changelog
+   roadmap
+   related_software
diff --git a/sktime/annotation/__init__.py b/sktime/annotation/__init__.py
@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+"""Implements time series annotation."""
diff --git a/sktime/annotation/adapters/__init__.py b/sktime/annotation/adapters/__init__.py
@@ -1,4 +1,8 @@
+#!/usr/bin/env python3 -u
 # -*- coding: utf-8 -*-
+# copyright: sktime developers, BSD-3-Clause License (see LICENSE file)
+"""Implements adapters for time series annotation."""
+
 __all__ = ["PyODAnnotator"]
 
 from sktime.annotation.adapters._pyod import PyODAnnotator
diff --git a/sktime/annotation/adapters/_pyod.py b/sktime/annotation/adapters/_pyod.py
@@ -1,4 +1,8 @@
+#!/usr/bin/env python3 -u
 # -*- coding: utf-8 -*-
+# copyright: sktime developers, BSD-3-Clause License (see LICENSE file)
+"""Implements outlier detection from pyOD."""
+
 import numpy as np
 from sktime.annotation.base._base import BaseSeriesAnnotator
 
@@ -10,7 +14,7 @@
 
 
 class PyODAnnotator(BaseSeriesAnnotator):
-    """Transformer that applies outlier detector from pyOD
+    """Transformer that applies outlier detector from pyOD.
 
     Parameters
     ----------
@@ -51,7 +55,6 @@ def _fit(self, X, Y=None):
         -----
         Create fitted model that sets attributes ending in "_".
         """
-
         X_np = X.to_numpy()
 
         if len(X_np.shape) == 1:
@@ -74,7 +77,6 @@ def _predict(self, X):
         Y : pd.Series - annotations for sequence X
             exact format depends on annotation type
         """
-
         fmt = self.fmt
         labels = self.labels
 

diff --git a/sktime/annotation/base/__init__.py b/sktime/annotation/base/__init__.py
@@ -1,4 +1,8 @@
+#!/usr/bin/env python3 -u
 # -*- coding: utf-8 -*-
+# copyright: sktime developers, BSD-3-Clause License (see LICENSE file)
+"""Implements base classes for annotation in sktime."""
+
 __all__ = ["BaseSeriesAnnotator"]
 
 from sktime.annotation.base._base import BaseSeriesAnnotator
diff --git a/sktime/annotation/base/_base.py b/sktime/annotation/base/_base.py
@@ -1,6 +1,8 @@
+#!/usr/bin/env python3 -u
 # -*- coding: utf-8 -*-
+# copyright: sktime developers, BSD-3-Clause License (see LICENSE file)
 """
-Base class template for annotator base type for time series stream
+Base class template for annotator base type for time series stream.
 
     class name: BaseSeriesAnnotator
 
@@ -77,6 +79,7 @@ def fit(self, X, Y=None):
             Training data to fit model to (time series).
         Y : pd.Series, optional
             Ground truth annotations for training if annotator is supervised.
+
         Returns
         -------
         self :
@@ -119,7 +122,6 @@ def predict(self, X):
         Y : pd.Series
             Annotations for sequence X exact format depends on annotation type.
         """
-
         self.check_is_fitted()
 
         X = check_series(X)
@@ -131,7 +133,7 @@ def predict(self, X):
         return Y
 
     def update(self, X, Y=None):
-        """update model with new data and optional ground truth annotations
+        """Update model with new data and optional ground truth annotations.
 
         Parameters
         ----------
@@ -149,7 +151,6 @@ def update(self, X, Y=None):
         -----
         Updates fitted model that updates attributes ending in "_".
         """
-
         self.check_is_fitted()
 
         X = check_series(X)
@@ -183,7 +184,6 @@ def update_predict(self, X):
         -----
         Updates fitted model that updates attributes ending in "_".
         """
-
         X = check_series(X)
 
         self.update(X=X)
@@ -252,7 +252,6 @@ def _update(self, X, Y=None):
         -----
         Updates fitted model that updates attributes ending in "_".
         """
-
         # default/fallback: re-fit to all data
         self._fit(self._X, self._Y)
 

diff --git a/sktime/base/_meta.py b/sktime/base/_meta.py
@@ -1,6 +1,7 @@
 #!/usr/bin/env python3 -u
 # -*- coding: utf-8 -*-
 # copyright: sktime developers, BSD-3-Clause License (see LICENSE file)
+"""Implements meta estimator for estimators composed of other estimators."""
 
 __author__ = ["Markus Löning"]
 __all__ = ["_HeterogenousMetaEstimator"]

diff --git a/sktime/classification/interval_based/_rise.py b/sktime/classification/interval_based/_rise.py
@@ -74,7 +74,7 @@ def _make_estimator(base_estimator, random_state=None):
 
 
 def _select_interval(min_interval, max_interval, series_length, rng, method=3):
-    """private function used to select an interval for a single tree."""
+    """Private function used to select an interval for a single tree."""
     interval = np.empty(2, dtype=int)
     if method == 0:
         interval[0] = rng.randint(series_length - min_interval)
@@ -308,7 +308,9 @@ def fit(self, X, y):
         return self
 
     def predict(self, X):
-        """Find predictions for all cases in X. Built on top of `predict_proba.
+        """Find predictions for all cases in X.
+
+        Built on top of `predict_proba`.
 
         Parameters
         ----------
@@ -538,7 +540,8 @@ def matrix_acf(x, num_cases, max_lag):
 
 
 def ps(x, sign=1, n=None, pad="mean"):
-    """
+    """Power spectrum transformer.
+
     Power spectrum transform, currently calculated using np function.
     It would be worth looking at ff implementation, see difference in speed
     to java.

diff --git a/sktime/datasets/base.py b/sktime/datasets/base.py
@@ -755,8 +755,7 @@ def load_uschange(y_name="Consumption"):
 
 
 def load_PBS_dataset():
-    """
-    Load the Pharmaceutical Benefit Scheme univariate time series dataset [1].
+    """Load the Pharmaceutical Benefit Scheme univariate time series dataset [1].
 
     Returns
     -------

diff --git a/sktime/datasets/tsc_dataset_names.py b/sktime/datasets/tsc_dataset_names.py
@@ -1,4 +1,5 @@
 # -*- coding: utf-8 -*-
+
 """
 List of datasets available from the timeseriesclassification.com archive.
 

diff --git a/sktime/forecasting/all/__init__.py b/sktime/forecasting/all/__init__.py
@@ -1,5 +1,8 @@
-#!/usr/bin/env python3 -u
 # -*- coding: utf-8 -*-
+# !/usr/bin/env python3 -u
+# copyright: sktime developers, BSD-3-Clause License (see LICENSE file)
+"""Import all time series forecasting functionality available in sktime."""
+
 __author__ = ["Markus Löning"]
 __all__ = [
     "ForecastingHorizon",

diff --git a/sktime/forecasting/base/__init__.py b/sktime/forecasting/base/__init__.py
@@ -1,4 +1,8 @@
 # -*- coding: utf-8 -*-
+# !/usr/bin/env python3 -u
+# copyright: sktime developers, BSD-3-Clause License (see LICENSE file)
+"""Implements base classes for forecasting in sktime."""
+
 __all__ = [
     "ForecastingHorizon",
     "BaseForecaster",