Reformat docs (#567)

* Add mock model and examples for decorators, checkpointers and csv logger. * Fix no model test * Fix MockModel in Py2 and dataset variational tests * More examples * More examples * Add some trial examples * Remove bad characters * More examples * Trial inline examples * Add tensorboard examples * Fix test * Reformat docs * Update docstring
pytorchbearer · Jun 12, 2019 · f3b2a77 · f3b2a77
1 parent b244c5d
commit f3b2a77
Show file tree

Hide file tree

Showing 12 changed files with 225 additions and 226 deletions.
diff --git a/docs/code/callbacks.rst b/docs/code/callbacks.rst
@@ -1,6 +1,110 @@
 torchbearer.callbacks
 ====================================
 
-..  automodule:: torchbearer.callbacks
-	:members:
-	:undoc-members:
+Base Classes
+------------------------------------
+..  autoclass:: torchbearer.bases.Callback
+        :members:
+        :undoc-members:
+
+..  automodule:: torchbearer.callbacks.callbacks
+        :members:
+        :undoc-members:
+
+Imaging
+------------------------------------
+
+Main Classes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+..  automodule:: torchbearer.callbacks.imaging.imaging
+        :members:
+        :undoc-members:
+
+Deep Inside Convolutional Networks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: torchbearer.callbacks.imaging.inside_cnns
+        :members:
+        :undoc-members:
+
+Model Checkpointers
+------------------------------------
+
+..  automodule:: torchbearer.callbacks.checkpointers
+        :members:
+        :undoc-members:
+
+Logging
+------------------------------------
+
+..  automodule:: torchbearer.callbacks.csv_logger
+        :members:
+        :undoc-members:
+
+..  automodule:: torchbearer.callbacks.printer
+        :members:
+        :undoc-members:
+
+Tensorboard, Visdom and Others
+------------------------------------
+
+..  automodule:: torchbearer.callbacks.tensor_board
+        :members:
+        :undoc-members:
+
+..  autoclass:: torchbearer.callbacks.live_loss_plot.LiveLossPlot
+        :members:
+        :undoc-members:
+
+Early Stopping
+------------------------------------
+
+..  automodule:: torchbearer.callbacks.early_stopping
+        :members:
+        :undoc-members:
+
+..  automodule:: torchbearer.callbacks.terminate_on_nan
+        :members:
+        :undoc-members:
+
+Gradient Clipping
+------------------------------------
+
+..  automodule:: torchbearer.callbacks.gradient_clipping
+        :members:
+        :undoc-members:
+
+Learning Rate Schedulers
+------------------------------------
+
+..  automodule:: torchbearer.callbacks.torch_scheduler
+        :members:
+        :undoc-members:
+
+
+Learning Rate Finders
+------------------------------------
+
+..  automodule:: torchbearer.callbacks.lr_finder
+        :members:
+        :undoc-members:
+
+Weight Decay
+------------------------------------
+
+..  automodule:: torchbearer.callbacks.weight_decay
+        :members:
+        :undoc-members:
+
+Weight / Bias Initialisation
+------------------------------------
+
+..  automodule:: torchbearer.callbacks.init
+        :members:
+        :undoc-members:
+
+Decorators
+------------------------------------
+
+..  automodule:: torchbearer.callbacks.decorators
+        :members:
+        :undoc-members:
diff --git a/docs/code/main.rst b/docs/code/main.rst
@@ -1,6 +1,62 @@
 torchbearer
 ====================================
 
-..  automodule:: torchbearer
-	:members:
-	:undoc-members:
+Trial
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Trial
+--------------------
+
+..  autoclass:: torchbearer.Trial
+        :members:
+        :undoc-members:
+
+Batch Loaders
+--------------------
+..  autofunction:: torchbearer.trial.load_batch_infinite
+..  autofunction:: torchbearer.trial.load_batch_none
+..  autofunction:: torchbearer.trial.load_batch_predict
+..  autofunction:: torchbearer.trial.load_batch_standard
+
+Misc
+--------------------
+..  autofunction:: torchbearer.trial.deep_to
+..  autofunction:: torchbearer.trial.update_device_and_dtype
+
+
+
+State
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The state is central in torchbearer, storing all of the relevant intermediate values that may be changed or replaced
+during model fitting. This module defines classes for interacting with state and all of the built in state keys used
+throughout torchbearer. The :func:`state_key` function can be used to create custom state keys for use in callbacks or
+metrics.
+
+Example::
+
+    >>> from torchbearer import state_key
+    >>> MY_KEY = state_key('my_test_key')
+
+State
+--------------------
+..  automodule:: torchbearer.state
+        :members: State, StateKey, state_key
+        :undoc-members:
+
+Key List
+--------------------
+..  automodule:: torchbearer.state
+        :noindex: State, StateKey, state_key
+        :exclude-members: State, StateKey, state_key
+        :members:
+        :undoc-members:
+
+Utilities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+..  automodule:: torchbearer.cv_utils
+        :members:
+        :undoc-members:
+
+.. autofunction:: torchbearer.bases.base_closure
+
diff --git a/docs/code/metrics.rst b/docs/code/metrics.rst
@@ -1,6 +1,61 @@
 torchbearer.metrics
 ====================================
+The base metric classes exist to enable complex data flow requirements between metrics. All metrics are either instances
+of :class:`.Metric` or :class:`MetricFactory`. These can then be collected in a :class:`MetricList` or a
+:class:`MetricTree`. The :class:`MetricList` simply aggregates calls from a list of metrics, whereas the
+:class:`MetricTree` will pass data from its root metric to each child and collect the outputs. This enables complex
+running metrics and statistics, without needing to compute the underlying values more than once. Typically,
+constructions of this kind should be handled using the :mod:`decorator API <.metrics.decorators>`.
+
+Base Classes
+------------------------------------
+
+..  autoclass:: torchbearer.bases.Metric
+        :members:
+        :undoc-members:
+
+..  automodule:: torchbearer.metrics.metrics
+        :members:
+        :undoc-members:
+
+Decorators - The Decorator API
+------------------------------------
+
+..  automodule:: torchbearer.metrics.decorators
+        :members:
+        :undoc-members:
+
+Metric Wrappers
+------------------------------------
+
+..  automodule:: torchbearer.metrics.wrappers
+        :members:
+        :undoc-members:
+
+Metric Aggregators
+------------------------------------
+
+..  automodule:: torchbearer.metrics.aggregators
+        :members:
+        :undoc-members:
+
+Base Metrics
+------------------------------------
+
+..  automodule:: torchbearer.metrics.default
+        :members:
+
+..  automodule:: torchbearer.metrics.primitives
+        :members:
+
+..  automodule:: torchbearer.metrics.roc_auc_score
+        :members:
+
+
+Timer
+------------------------------------
+..  automodule:: torchbearer.metrics.timer
+        :members:
+        :undoc-members:
 
-..  automodule:: torchbearer.metrics
-    :members:
 
diff --git a/docs/code/variational.rst b/docs/code/variational.rst
diff --git a/torchbearer/__init__.py b/torchbearer/__init__.py
@@ -1,26 +1,3 @@
-"""
-Trial
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-..  automodule:: torchbearer.trial
-        :members:
-        :undoc-members:
-
-State
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-..  automodule:: torchbearer.state
-        :members:
-        :undoc-members:
-
-Utilities
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-..  automodule:: torchbearer.cv_utils
-        :members:
-        :undoc-members:
-"""
-
 from .version import __version__
 from . import magics
 from .bases import no_grad, enable_grad, cite, base_closure, Callback, Metric

diff --git a/torchbearer/callbacks/__init__.py b/torchbearer/callbacks/__init__.py
@@ -1,102 +1,3 @@
-"""
-Base Classes
-------------------------------------
-
-..  automodule:: torchbearer.callbacks.callbacks
-        :members:
-        :undoc-members:
-
-Imaging
-------------------------------------
-
-..  automodule:: torchbearer.callbacks.imaging
-        :members:
-        :undoc-members:
-
-Model Checkpointers
-------------------------------------
-
-..  automodule:: torchbearer.callbacks.checkpointers
-        :members:
-        :undoc-members:
-
-Logging
-------------------------------------
-
-..  automodule:: torchbearer.callbacks.csv_logger
-        :members:
-        :undoc-members:
-
-..  automodule:: torchbearer.callbacks.printer
-        :members:
-        :undoc-members:
-
-Tensorboard, Visdom and Others
-------------------------------------
-
-..  automodule:: torchbearer.callbacks.tensor_board
-        :members:
-        :undoc-members:
-
-..  autoclass:: torchbearer.callbacks.live_loss_plot.LiveLossPlot
-        :members:
-        :undoc-members:
-
-Early Stopping
-------------------------------------
-
-..  automodule:: torchbearer.callbacks.early_stopping
-        :members:
-        :undoc-members:
-
-..  automodule:: torchbearer.callbacks.terminate_on_nan
-        :members:
-        :undoc-members:
-
-Gradient Clipping
-------------------------------------
-
-..  automodule:: torchbearer.callbacks.gradient_clipping
-        :members:
-        :undoc-members:
-
-Learning Rate Schedulers
-------------------------------------
-
-..  automodule:: torchbearer.callbacks.torch_scheduler
-        :members:
-        :undoc-members:
-
-
-Learning Rate Finders
-------------------------------------
-
-..  automodule:: torchbearer.callbacks.lr_finder
-        :members:
-        :undoc-members:
-
-Weight Decay
-------------------------------------
-
-..  automodule:: torchbearer.callbacks.weight_decay
-        :members:
-        :undoc-members:
-
-Weight / Bias Initialisation
-------------------------------------
-
-..  automodule:: torchbearer.callbacks.init
-        :members:
-        :undoc-members:
-
-Decorators
-------------------------------------
-
-..  automodule:: torchbearer.callbacks.decorators
-        :members:
-        :undoc-members:
-"""
-
 from torchbearer import Callback
 from .callbacks import *
 from .lr_finder import CyclicLR

diff --git a/torchbearer/callbacks/callbacks.py b/torchbearer/callbacks/callbacks.py
@@ -1,9 +1,3 @@
-"""
-..  autoclass:: torchbearer.bases.Callback
-        :members:
-        :undoc-members:
-"""
-
 from torchbearer import Callback