Improve State and Engine docs

🚀 Feature

Currently, if we execute twice trainer.run we can fall into the following situation:

# ...
trainer.run(train_loader, max_epochs=5)

# reset model weights etc and rerun
trainer.run(train_loader, max_epochs=2)
> ValueError: Argument max_epochs should be larger than the start epoch defined in the state: 2 vs 5

But if we would like to restart the training from the begining, we have to reset trainer.state as

trainer.run(train_loader, max_epochs=5)

# reset model weights etc and rerun
trainer.state.max_epochs = None
trainer.run(train_loader, max_epochs=2)

Let’s improve two things:

1. let’s provide State.restart() method that just sets state.max_epochs = None
2. Add a note into Engine.run docstring saying if we would like to restart the training from zero, we have to either call trainer.state.restart() or trainer.state.max_epochs = None.
3. Improve the message “ValueError: Argument max_epochs should be larger than the start epoch defined in the state: 2 vs 5” by adding something like “Please, call state.restart() before calling engine.run() if would like to restart from zero.”

For Hacktoberfest contributors, feel free to ask questions for details if any and say that you would like to tackle the issue. Please, take a look at CONTRIBUTING guide.

[sdesrozis]

Just a remark, having a restart() method lets user call it when he wants, even if it’s not the good time. Why do not have such feature in the trainer ? No way to misuse it. What do you think ? @vfdev-5 @fco-dv

[vfdev-5]

I’m not fan of introducing new arg like restart …