Restructure documentation into examples, tutorials and an improved API reference

[hakonanes]

I plan to restructure the orix documentation in a similar fashion as I've done in kikuchipy, based on the Diátaxis framework.

The changes I plan:

• Separate the user guide into Examples and Tutorials. The examples are task oriented (no/minimal explanations), while the tutorials are learning oriented.
• Examples are short recipies of common tasks in orix (e.g. #370, #364, #332) represented in a sphinx-gallery from Python scripts (not notebooks), very similar to Matplotlib's or scikit-images'. Whenever we have nice plot we've made or a procedure which we think might be useful to others, we can add an example to the appropriate section (or make a new section). This is better than trying to shoehorn more stuff into the appropriate tutorial. See the kikuchipy examples for an example.
• Citing Diátaxis, tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. These will be the existing user guides, built from notebooks with nbsphinx. See the kikuchipy tutorials for an example.
• The API reference will get an overhaul, with one listing the top modules, then one page per module listing classes and functions, then one page per class listing methods and attributes, then one page per method and attribute. These pages are automatically generated when building the docs with make html, and using custom Sphinx templates and some smart use of Sphinx, we shouldn't have to remember to list every method and attribute manually in reference.rst. The result is a reference that is simpler to navigate and lists the example(s) where this particular functionality is used. See the kikuchipy API for an example.

I've done this once for kikuchipy, so shouldn't be too difficult to do for orix.

[pc494]

This seems like an excellent addition; do you need any help?

[hakonanes]

Yes please, that would be great!

I hope to make a PR tomorrow with the framework. After that, any help with adding examples (snippets), either new ones or from the tutorials to examples, would be appreciated. And expanding on the current reference docstring examples.

[hakonanes]

Couldn't get to this this weekend, so it has to wait for a couple of weeks.

[pc494]

No worries, will jump in when the framework is up :)