Add kikuchipy.data module with tests, update changelog/contrib. guide

Signed-off-by: Håkon Wiik Ånes <hwaanes@gmail.com>

doc/bibliography.bib

@@ -0,0 +1,36 @@
+@article{wright2015introduction,
+	author = {Wright, Stuart I. and Nowell, Matthew M. and Lindeman, Scott P. and Camus, Patrick P. and {De Graef}, Marc and Jackson, Michael A.},
+	doi = {10.1016/j.ultramic.2015.08.001},
+	issn = {18792723},
+	journal = {Ultramicroscopy},
+	keywords = {EBSD, Electron Backscatter Diffraction, indexing, orientation{\_}averaging},
+	mendeley-tags = {indexing,orientation{\_}averaging},
+	pages = {81–94},
+	pmid = {26342553},
+	publisher = {Elsevier},
+	title = {{Introduction and comparison of new EBSD post-processing methodologies}},
+	volume = {159},
+	year = {2015}
+}
+@article{marquardt2017quantitative,
+	author = {Marquardt, Katharina and {De Graef}, Marc and Singh, Saransh and Marquardt, Hauke and Rosenthal, Anja and Koizuimi, Sanae},
+	doi = {10.2138/am-2017-6062},
+	issn = {19453027},
+	journal = {American Mineralogist},
+	keywords = {electron backscatter diffraction, dictionary indexing, indexing},
+	mendeley-tags = {ebsd,indexing},
+	number = {9},
+	pages = {1843–1855},
+	title = {{Quantitative electron backscatter diffraction (EBSD) data analyses using the dictionary indexing (DI) approach: Overcoming indexing difficulties on geological materials}},
+	volume = {102},
+	year = {2017}
+}
+@article{jackson2019dictionary,
+	author = {Jackson, Michael A. and Pascal, Elena and {De Graef}, Marc},
+	journal = {Integrating Materials and Manufacturing Innovation},
+	pages = {1–21},
+	publisher = {Springer},
+	title = {{Dictionary Indexing of Electron Back-Scatter Diffraction Patterns: a Hands-On Tutorial}},
+	year = {2019},
+	doi = {10.1007/s40192-019-00137-4},
+}

doc/bibliography.rst

@@ -0,0 +1,6 @@
+============
+Bibliography
+============
+
+.. bibliography:: bibliography.bib
+   :cited:

doc/changelog.rst

@@ -22,6 +22,9 @@ Contributors
 
 Added
 -----
+- A kikuchipy.data module, starting with a small Nickel data set with 9
+  patterns, meant to be used for testing and in the user guide.
+  (`#236 <https://github.com/pyxem/kikuchipy/pull/236>`_)
 - Indexing of EBSD patterns through matching of patterns with a static
   dictionary of simulated patterns with known orientations.
   (`#231 <https://github.com/pyxem/kikuchipy/pull/231>`_,
@@ -49,6 +52,9 @@ Added
 
 Changed
 -------
+- Migrating the user guide from `reStructuredText` files to Jupyter Notebooks
+  built to HTML via the `nbsphinx` package.
+  (`#236 <https://github.com/pyxem/kikuchipy/pull/236>`_)
 - Move GitHub repository to the pyxem organization. Update relevant URLs.
   (`#198 <https://github.com/pyxem/kikuchipy/pull/198>`_)
 - Allow scikit-image >= 0.16.

doc/conf.py

@@ -31,6 +31,7 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    "sphinxcontrib.bibtex",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
@@ -102,6 +103,38 @@
 # Figure references
 numfig = True
 
+# nbsphinx configuration
+# Taken from nbsphinx' own nbsphinx configuration file.
+# This is processed by Jinja2 and inserted before each notebook
+nbsphinx_prolog = r"""
+{% set docname = 'doc/' + env.doc2path(env.docname, base=None) %}
+
+.. raw:: html
+
+    <div class="admonition note">
+      This page was generated from
+      <a class="reference external" href="https://github.com/pyxem/kikuchipy/blob/{{ env.config.release|e }}/{{ docname|e }}">{{ docname|e }}</a>.
+      <script>
+        if (document.location.host) {
+          $(document.currentScript).replaceWith(
+            '<a class="reference external" ' +
+            'href="https://nbviewer.jupyter.org/url' +
+            (window.location.protocol == 'https:' ? 's/' : '/') +
+            window.location.host +
+            window.location.pathname.slice(0, -4) +
+            'ipynb">View in <em>nbviewer</em></a>.'
+          );
+        }
+      </script>
+    </div>
+
+.. raw:: latex
+
+    \nbsphinxstartnotebook{\scriptsize\noindent\strut
+    \textcolor{gray}{The following section was generated from
+    \sphinxcode{\sphinxupquote{\strut {{ docname | escape_latex }}}} \dotfill}}
+"""
+
 
 def linkcode_resolve(domain, info):
     """Determine the URL corresponding to Python object.

doc/contributing.rst

@@ -117,10 +117,10 @@ You can then make a `pull request
 <https://guides.github.com/activities/forking/#making-a-pull-request>`_ to
 kikuchipy's ``master`` branch. Good job!
 
-.. _building-the-documentation:
+.. _building-and-writing-documentation:
 
-Building the documentation
-==========================
+Building and writing documentation
+==================================
 
 We use `Sphinx <https://www.sphinx-doc.org/en/master/>`_ for documenting
 functionality. Install necessary dependencies to build the documentation::
@@ -133,12 +133,28 @@ Then, build the documentation from the ``doc`` directory::
    $ make html
 
 The documentation's ``html`` pages are built in the ``doc/build/html`` directory
-from files in the `reStructuredText
+from files in the `reStructuredText (reST)
 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
 plaintext markup language. They should be accessible in the browser by typing
 ``file:///your-absolute/path/to/kikuchipy/doc/build/html/index.html`` in the
 address bar.
 
+Tips for writing Jupyter Notebooks that are meant to be converted to `reST` text
+files by `nbsphinx <https://nbsphinx.readthedocs.io/en/latest/>`_:
+
+- Use ``_ = ax[0].imshow(...)`` to disable Matplotlib output if a Matplotlib
+  command is the last line in a cell (as per
+  `this Stack Overflow question <https://stackoverflow.com/questions/12056115/disable-the-output-of-matplotlib-pyplot>`_).
+- Cite some work? Add a bibtex entry in the ``bibliography.bib`` file and cite
+  it with this HTML in a Markdown cell
+  ``<cite data-cite="bibtex-id">Flintstone et al. (10 000 BC.)</cite>``.
+- Refer to the API reference with this Markdown
+  ``[fft_filter()](reference.rst#kikuchipy.signals.EBSD.fft_filter)``. Remember
+  to add the function/method parantheses ``()``.
+- Reference external APIs (because ``intersphinx`` isn't supported) via standard
+  Markdown
+  ``[Signal2D](http://hyperspy.org/hyperspy-doc/current/api/hyperspy._signals.signal2d.html)``.
+
 .. _running-and-writing-tests:
 
 Running and writing tests

doc/index.rst

@@ -17,14 +17,14 @@ kikuchipy
     load_save_data.rst
     reference_frames.rst
     change_scan_pattern_size.rst
-    pattern_processing.rst
-    pattern_processing2.ipynb
+    pattern_processing.ipynb
     feature_maps.rst
     virtual_backscatter_electron_imaging.rst
     visualizing_patterns.rst
     multivariate_analysis.rst
     metadata.rst
     reference.rst
+    bibliography.rst
 
 .. toctree::
     :hidden: