Fix readthedocs conf. And additional API docs. (#1322)

* Last changes

* Last changes

* Last changes

* Last changes

* Last changes

* docs requirements fix

* Last changes

.readthedocs.yml

@@ -4,6 +4,11 @@
 
 version: 2
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+
 sphinx:
   builder: html
   configuration: docs/conf.py

README.md

@@ -113,6 +113,8 @@ pytest -m 'dockertest'
 
 ### Build the documentation
 
+This command will run the local documentation server:
+
 ```console
 > cd docs/
 > make watch

docs/api/builder.rst

@@ -2,15 +2,15 @@ Builder
 -------
 
 Model builder
-=============
+^^^^^^^^^^^^^
 .. automodule:: gordo.builder.build_model
     :members:
     :undoc-members:
     :show-inheritance:
 
 
 Local Model builder
-===================
+^^^^^^^^^^^^^^^^^^^
 
 This is meant to provide a good way to validate a configuration file
 as well as to enable creating and testing models locally with little overhead.
@@ -20,3 +20,10 @@ as well as to enable creating and testing models locally with little overhead.
     :undoc-members:
     :show-inheritance:
 
+Model builder utils
+^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: gordo.builder.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/cli.rst

@@ -0,0 +1,12 @@
+CLI
+---
+
+.. automodule:: gordo.cli.exceptions_reporter
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: gordo.cli.custom_types
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/index.rst

@@ -7,6 +7,8 @@ API
     ./builder.rst
     ./serializer.rst
     ./util.rst
+    ./cli.rst
+    ./reporters.rst
     ./workflow.rst
     ./server/index.rst
     ./machine/index.rst

docs/api/machine/index.rst

@@ -7,4 +7,5 @@ Machine
     ./machine.rst
     ./metadata.rst
     ./validators.rst
+    ./loader.rst
     ./model/index.rst

docs/api/machine/loader.rst

@@ -0,0 +1,7 @@
+Loader
+------
+
+.. automodule:: gordo.machine.loader
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/machine/machine.rst

@@ -1,10 +1,20 @@
 Machine
 -------
 
-A ``Machine`` is the central unity of a model, dataset, metadata and everything
+A :class:`gordo.machine.Machine` is the central unity of a model, dataset, metadata and everything
 needed to create and build a ML model.
 
 .. automodule:: gordo.machine.machine
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: gordo.machine.encoders
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: gordo.machine.constants
     :members:
     :undoc-members:
     :show-inheritance:

docs/api/machine/model/anomaly.rst

@@ -1,12 +1,12 @@
 Anomaly Models
 --------------
 
-Models which implment a ``.anomaly(X, y)`` and can be served under the
-model server ``/anomaly/prediction`` endpoint.
+Models which implment a :func:`gordo.machine.model.anomaly.base.AnomalyDetectorBase.anomaly` and can be served under the
+model server :ref:`post-prediction` endpoint.
 
 
 AnomalyDetectorBase
-===================
+^^^^^^^^^^^^^^^^^^^
 
 The base class for all other anomaly detector models
 
@@ -17,10 +17,10 @@ The base class for all other anomaly detector models
 
 
 DiffBasedAnomalyDetector
-========================
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Calculates the absolute value prediction differences between y and yhat as well
-as the absolute difference error between both matrices via ``numpy.linalg.norm(..., axis=1)``
+as the absolute difference error between both matrices via :func:`numpy.linalg.norm`
 
 .. automodule:: gordo.machine.model.anomaly.diff
     :members:

docs/api/machine/model/index.rst

@@ -4,7 +4,10 @@ Model
 .. toctree::
     :maxdepth: 2
 
+    ./model.rst
     ./anomaly.rst
     ./model-factories.rst
     ./transformer-funcs.rst
-    ./transformers.rst
+    ./transformers.rst
+    ./register.rst
+    ./utils.rst

docs/api/machine/model/model-factories.rst

@@ -5,24 +5,32 @@ Model factories are stand alone functions which take an arbitrary number of
 primitive parameters (int, float, list, dict, etc) and return a model which
 can then be used in the ``kind`` parameter of some Scikit-Learn like wrapper model.
 
-An example of this is ``KerasAutoEncoder`` which accepts a ``kind`` argument
-(as all custom gordo models do) and can be given `feedforward_model`. Meaning
+An example of this is :class:`gordo.machine.model.models.KerasAutoEncoder` which accepts a ``kind`` argument
+(as all custom gordo models do) and can be given ``feedforward_model``. Meaning
 that function will be used to create the underlying Keras model for
 ``KerasAutoEncoder``
 
 
 feedforward factories
-=====================
+^^^^^^^^^^^^^^^^^^^^^
 
 .. automodule:: gordo.machine.model.factories.feedforward_autoencoder
     :members:
     :undoc-members:
     :show-inheritance:
 
 lstm factories
-==============
+^^^^^^^^^^^^^^
 
 .. automodule:: gordo.machine.model.factories.lstm_autoencoder
     :members:
     :undoc-members:
     :show-inheritance:
+
+Utils
+^^^^^
+
+.. automodule:: gordo.machine.model.factories.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/machine/model/model.rst

@@ -0,0 +1,12 @@
+Model
+-----
+
+.. automodule:: gordo.machine.model.base
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: gordo.machine.model.models
+     :members:
+     :undoc-members:
+     :show-inheritance:

docs/api/machine/model/register.rst

@@ -0,0 +1,7 @@
+Register
+--------
+
+.. automodule:: gordo.machine.model.register
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/machine/model/transformer-funcs.rst

@@ -2,7 +2,7 @@ Transformer Functions
 ---------------------
 
 A collection of functions which can be referenced within the
-``sklearn.preprocessing.FunctionTransformer`` transformer.
+:class:``sklearn.preprocessing.FunctionTransformer`` transformer.
 
 General
 =======

docs/api/machine/model/transformers.rst

@@ -3,7 +3,7 @@ Transformers
 
 Specialized transformers to address Gordo specific problems.
 This function just like Scikit-Learn's transformers and thus can be
-inserted into ``Pipeline`` objects.
+inserted into :class:`sklearn.pipeline.Pipeline` objects.
 
 Imputers
 ========

docs/api/machine/model/utils.rst

@@ -0,0 +1,7 @@
+Utils
+-----
+
+.. automodule:: gordo.machine.model.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/machine/validators.rst

@@ -1,5 +1,5 @@
-Descriptors
------------
+Validators
+----------
 
 Collection of descriptors to verify types and conditions of the Machine
 attributes when loading.

docs/api/reporters.rst

@@ -0,0 +1,22 @@
+Reporters
+---------
+
+.. automodule:: gordo.reporters.base
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: gordo.reporters.exceptions
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: gordo.reporters.mlflow
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: gordo.reporters.postgres
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/serializer.rst

@@ -16,7 +16,7 @@ objects which will be (de)serialized by the serializer to complete this goal.
 
 
 From Definition
-===============
+^^^^^^^^^^^^^^^
 
 The ability to take a 'raw' representation of an object in ``dict`` form
 and load it into a Python object.
@@ -28,7 +28,7 @@ and load it into a Python object.
 
 
 Into Definitiion
-================
+^^^^^^^^^^^^^^^^
 
 The ability to take a Python object, such as a scikit-learn
 pipeline and convert it into a primitive ``dict``, which can then be inserted
@@ -38,3 +38,11 @@ into a YAML config file.
     :members:
     :undoc-members:
     :show-inheritance:
+
+Utils
+^^^^^
+
+.. automodule:: gordo.serializer.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/server/index.rst

@@ -6,5 +6,7 @@ Server
 
     ./server.rst
     ./base.rst
+    ./properties.rst
     ./anomaly.rst
+    ./prometheus.rst
     ./utils.rst

docs/api/server/prometheus.rst

@@ -0,0 +1,17 @@
+Prometheus
+----------
+
+.. automodule:: gordo.server.prometheus.metrics
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: gordo.server.prometheus.server
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: gordo.server.prometheus.gunicorn_config
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/server/properties.rst

@@ -0,0 +1,7 @@
+Properties
+----------
+
+.. automodule:: gordo.server.properties
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/util.rst

@@ -3,16 +3,27 @@ Util
 
 Project helpers, and associated functionality which have no home.
 
-Disk Registry
-=============
-.. automodule:: gordo.util.disk_registry
+.. automodule:: gordo.utils
     :members:
     :undoc-members:
     :show-inheritance:
 
-Utils
-=====
 .. automodule:: gordo.util.utils
     :members:
     :undoc-members:
     :show-inheritance:
+
+.. automodule:: gordo.util.text
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: gordo.util.version
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: gordo.util.disk_registry
+    :members:
+    :undoc-members:
+    :show-inheritance: