Renewal of the MDP documentation

[NiMlr]

Hi developers of MDP,

I am creating this issue to track future efforts for updating the documentation to the newest dependency versions. The update can include a remake or replacement of the custom extensions, conversion of the code snippets, and fixes for the build to work with the newest dependency versions.

Below I listed some steps I have already taken and some that are still to be done. I am hoping to discuss some decisions.

UPDATE 28/04/2020 22:45 UTC+1:

• Update the following files to work with the newest dependency versions. Any occurring errors or warnings should be listed as an issue such that a decision can be made on how to proceed.

  • ./examples/bimdp_examples/bimdp_hinet_inspection.rst
  • ./examples/bimdp_examples/bimdp_custom_inspection.rst
  • ./examples/bimdp_examples/bimdp_inverse.rst
  • ./examples/binetdbn/dbn_binodes.rst
  • ./examples/binetdbn/dbn.rst
  • ./examples/binetdbn/test_dbnnodes.rst
  • ./examples/binetdbn/dbn_binodes_statemachine_old.rst
  • ./examples/binetdbn/dbn_binodes_coroutine_old.rst
  • ./examples/binetdbn/dbn_nodes.rst
  • ./examples/examples.rst
  • ./examples/slideshow/slideshow.rst
  • ./examples/convolution/image_convolution.rst
  • ./examples/gng/animated_training.rst
  • ./examples/gng/gng.rst
  • ./examples/lle/lle.rst
  • ./examples/gradnewton/gradnewton.rst
  • ./examples/logmap/logmap.rst
  • ./examples/bayes_guesser/bayes_guesser.rst
  • ./examples/word_generator/word_generator.rst
  • ./examples/logo/logo_animation.rst
  • ./examples/scikits_learn/digit_classification.rst
  • ./contact.rst
  • ./node_list.rst
  • ./license.rst
  • ./install.rst
  • ./main.rst
  • ./documentation.rst
  • ./additional_utilities.rst
  • ./talks/talks.rst
  • ./tutorial/quick_start.rst
  • ./tutorial/hinet.rst
  • ./tutorial/bimdp.rst
  • ./tutorial/extensions.rst
  • ./tutorial/iterables.rst
  • ./tutorial/nodes.rst
  • ./tutorial/introduction.rst
  • ./tutorial/caching.rst
  • ./tutorial/classifiers.rst
  • ./tutorial/parallel.rst
  • ./tutorial/wrappers.rst
  • ./tutorial/using_mdp_is_as_easy.rst
  • ./tutorial/checkpoints.rst
  • ./tutorial/flows.rst
  • ./tutorial/tutorial.rst
  • ./time_machine.rst
  • ./index.rst
  • ./development.rst
  • ./how_to_cite_mdp.rst

• Write a short guide on how to compile the docs locally and add it to the development guide in the documentation.

• Autobuild documentation for pull requests.

• Adapt the remaining part of the docstrings to properly fit the rst-style to solve the warnings popping up in the sphinx-build.

• Discuss any further improvements that could be made.

• Migrate all example code in the docs to python 3.

• Re-introduce doctest in the doc building pipeline.

To check out the new documentation locally install sphinx, run sphinx-build source build -v on the top level of the repository and open the index.html in /build. You need to make sure to clone/pull the submodule as well in order to build the documentation.

I am looking forward to your feedback.