Docs migration: finish migration of the README

[lmoureaux]

Description

This PR migrates the remaining parts of the README to the Sphinx system.

It also changes the structure of the documentation to keep the table of contents readable.

This should be enough to close #94, even though:

• Part of the documentation can only be found on the DOC TWiki
• Not all comments in python modules have been converted into docstrings yet
• Sphinx is still unhappy about some constructs in the preexisting docstrings

Types of changes

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [x] Breaking change (fix or feature that would cause existing functionality to change)

Motivation and Context

94

How Has This Been Tested?

The documentation was generated. As usual, it can be viewed here

Checklist:

• [x] My code follows the code style of this project.
• [x] My change requires a change to the documentation.
• [x] I have updated the documentation accordingly.
• [ ] I have added tests to cover my changes.
• [ ] All new and existing tests passed.

[lmoureaux]

Addressed comments.

[bdorney]

Some minor tweaks needed; given that @lmoureaux this can either sit for two weeks or we merge and someone opens an interim PR between now and then.

[lmoureaux]

• Rebased on top of current develop
• Addressed new comments

[bdorney]

One minor comment still unaddressed. Needs rebase ontop of develop.

[lmoureaux]

• Rebased on top of current develop
• Restored plot_eff.py example