Improve documentation structure and clarity

[Sheila-nk]

The current documentation, hosted on GitHub Pages: https://scipy.github.io/scipy_doctest/ , could use some improvements to make it clearer and more user-friendly.

This issue is a place to discuss potential changes and enhancements so that the docs are easy to navigate and helpful for users. Feedback and suggestions are welcome!

[Sheila-nk]

@ev-br you had mentioned that we should split up the README into logical bits as well as add free-form content alongside API docs.
Could you clarify what specific changes you'd like to see so we can align on the best approach? Thanks!

[ev-br]

Now that I read the rendered documentation, I got to kind of like how the README is reused for, well, the readme file and the narrative docs. Now that it's rendered, a few straightforward improvement seem possible:

• make mentions of DT* classes into links to their respective API docs
• stress that stopwords are similar to # may vary, only kept at the tool not in the docstrings
• stress that pseudocode is similar to # doctest: + SKIP, only kept at the tool
• expand the doctest discovery section, link to a section which explains --doctest-collect=api behavior

For the API docs, we need to:

• document find_doctests
• expand the docstring of DTFinder with the links to find_doctests
• document the doctest layer (testmod, testfile), stress that their API closely follows that of the standard library doctest module, stress the difference (DTConfig)
• stress that DT* classes differ from the stdlib ones in that they receive a DTConfig instance.
• generally clean up and expand the docstrings.

EDIT:

• not sure how helpful are the API docs for DTModule and DTFile. These seem to be the plugin's implementation details.
• DT* classes: we probably do not need to document their attributes (either remove it from the doc build or make them _private)
• DT* class method listings: it seems the doc build picks up only methods we redefine from the superclasses. If so, should mention it

The list is by no means exhaustive, feel free to tweak other things though Sheila!