Repository: pytorch/ignite

Issue:
Improve State documentation
Hi,

I think the documentation of states and the way they're used by engines is not detailed enough.
Currently the only way to know what attributes are available in the default State object, used by the engines generated by convenience methods such as `create_supervised_trainer`, is to look at the source code.  
Some of them are mentioned in the [Concept](https://pytorch.org/ignite/concepts.html#state) part of the documentation but there is still a lot of room for confusion about the way they work and some are missing.
For example, no information about the `batch` attribute which without documentation some might assume to correspond to the batch index (kinda like `epoch` for the epoch index) which is actually `iteration`. Same thing for `epoch` which is used implicitly in examples but no mention of it in the default `State` documentation, and you might think it's obvious but then someone will try to create a default `State` and assume `epoch` is a built-in attribute set to 0 at instantiation when in fact you'll have to search through the source code to figure out that it's not a default attribute and is only created by the default `Engine` through a kwarg passed to the `State` class.

Additionally this kind of explicit documentation of the state should be done every time a custom `State` is created otherwise the user is left to guess what attributes are available in it, what they mean and what format they're in. For example, is `output` the return from the forward pass of your model? The loss?
You'll have to look at `Engine` then find out it's the output of the process_function argument. Then figure out that in the case of the  `create_supervised_trainer` that function is `_update` which returns `loss.item()` and in the case of `create_supervised_evaluator` returns `(y_pred, y)`.

Thank you, and sorry for the verbosity but without it I was afraid this would be rejected as trivial.


Discussion:
@EtienneDesticourt thanks for a great feedback. I agree that the docs on `State` may seem unclear.
If you would like to improve it, please, send a PR. We are really appreciate community contributions !

> You'll have to look at Engine then find out it's the output of the process_function argument. Then figure out that in the case of the create_supervised_trainer that function is _update which returns loss.item() and in the case of create_supervised_evaluator returns (y_pred, y).

Generally, `process_function` is defined by user when it is inserted to `Engine`. Probably, it is unclear that `engine.state.output` will contain the output of `process_function`, see [Concepts](https://pytorch.org/ignite/concepts.html#state). 
And I agree that the docstring of these `create_supervised*` should be improved to clearly indicate what is stored in `engine.state.output`.
  

Resolving patch:
diff --git a/ignite/__init__.py b/ignite/__init__.py
--- a/ignite/__init__.py
+++ b/ignite/__init__.py
@@ -3,5 +3,6 @@
 import ignite.metrics
 import ignite.exceptions
 import ignite.contrib
+import ignite.utils
 
 __version__ = '0.1.2'
diff --git a/ignite/engine/__init__.py b/ignite/engine/__init__.py
--- a/ignite/engine/__init__.py
+++ b/ignite/engine/__init__.py
@@ -30,6 +30,8 @@ def create_supervised_trainer(model, optimizer, loss_fn,
         prepare_batch (callable, optional): function that receives `batch`, `device`, `non_blocking` and outputs
             tuple of tensors `(batch_x, batch_y)`.
 
+    Note: `engine.state.output` for this engine is the loss of the processed batch.
+
     Returns:
         Engine: a trainer engine with supervised update function.
     """
@@ -65,6 +67,8 @@ def create_supervised_evaluator(model, metrics={},
         prepare_batch (callable, optional): function that receives `batch`, `device`, `non_blocking` and outputs
             tuple of tensors `(batch_x, batch_y)`.
 
+    Note: `engine.state.output` for this engine is a tuple of `(batch_pred, batch_y)`.
+
     Returns:
         Engine: an evaluator engine with supervised inference function.
     """


Test patch: