Add Documentation Examples

[CSSFrancis]

Description of the change

This depends on #205 and adds Examples to the documentation.

Progress of the PR

• [x] Docstrings for all functions
• [x] Unit tests with pytest for all lines
• [x] Clean code style by running black

For reviewers

• [ ] The PR title is short, concise, and will make sense 1 year later.
• [ ] New functions are imported in corresponding __init__.py.
• [ ] New features, API changes, and deprecations are mentioned in the unreleased section in CHANGELOG.rst.
• [ ] Contributor(s) are listed correctly in credits in diffsims/release_info.py and in .zenodo.json.

[CSSFrancis]

@hakonanes Any chance you can look over this if you get the chance? Mostly it just copies the examples in orix/pyxem

[hakonanes]

Yes, I can. But since this depends on #205, I'll do so after that one is reviewed and merged (I have some questions regarding the intensity attribute, e.g.).

[hakonanes]

I can review this once you rebase and make any changes you'd like.

[CSSFrancis]

@hakonanes what is your opinion on including the examples for the distribution?

[hakonanes]

I'd include them, as currently they are just small Python files.

[CSSFrancis]

@hakonanes This is good to be reviewed when you have the chance.

[hakonanes]

@CSSFrancis, if it's fine with you, I'll add the following fixes and updates to your branch:

• Use numpydoc instead of sphinx.ext.napoleon, giving us useful warnings for how to improve our docstrings
• Restructure doc/index.rst perfectly in line with orix (and fixing some links etc.)
• Fix minigalleries in API (since we use custom templates, we have to add it explicitly, which I forgot; sorry!)
• Rename Gallery of Examples -> Examples, and fix heading level (use === above and below)
• Some other smaller things

[CSSFrancis]

@CSSFrancis, if it's fine with you, I'll add the following fixes and updates to your branch:

• Use numpydoc instead of sphinx.ext.napoleon, giving us useful warnings for how to improve our docstrings
• Restructure doc/index.rst perfectly in line with orix (and fixing some links etc.)
• Fix minigalleries in API (since we use custom templates, we have to add it explicitly, which I forgot; sorry!)
• Rename Gallery of Examples -> Examples, and fix heading level (use === above and below)
• Some other smaller thing

@hakonanes Go for it! I'm pretty much always okay with you adding things to my PR's :).

[hakonanes]

Thanks, I've done so now. I'll go over the docs built in this PR tomorrow, and then we can merge and release.