Improve API reference, update installation guide, rename user guide t…

…o tutorials (#38)

* Align some parameter names, improve docstrings

Signed-off-by: Håkon Wiik Ånes <[email protected]>

* Improve docstrings, make some functions explicitly private

Signed-off-by: Håkon Wiik Ånes <[email protected]>

* Mention parameter changes in changelog

Signed-off-by: Håkon Wiik Ånes <[email protected]>

* Restructure documentation, improve reference API

Signed-off-by: Håkon Wiik Ånes <[email protected]>

* Try to fix Sphinx source code linking

Signed-off-by: Håkon Wiik Ånes <[email protected]>

* Revert change of except statement

Signed-off-by: Håkon Wiik Ånes <[email protected]>

* Corrected tutorial notebooks for new API
Corrected NLPAR tutorial API to be more consistent.

Signed-off by: David Rowenhorst <[email protected]>

Co-authored-by: David Rowenhorst <[email protected]>

.gitignore

@@ -11,7 +11,6 @@ report.log
 
 dist/
 
-
 # Jupyter
 **.ipynb_checkpoints
 
@@ -25,3 +24,4 @@ dist/
 
 # Sphinx
 doc/_build
+doc/reference/generated/

CHANGELOG.rst

@@ -13,6 +13,20 @@ Added
 - Explanation that the pixel size must be passed as the forth PC value whenever
   ``vendor=EMSOFT`` is used.
 
+Changed
+-------
+- Changed the parameter name ``patsIn`` to ``patsin`` in functions ``index_pats()`` and
+  ``index_pats_distributed()``, to be in line with ``EBSDIndex.index_pats()``, and
+  ``peakDetectPlan`` to ``bandDetectPlan`` in ``index_pats_distributed()``, to be in
+  line with the other two functions.
+- Reversed the order of the pattern height and width in the ``patDim`` parameter passed
+  to ``EBSDIndex.update_file()``: the new order is (height, width).
+
+Removed
+-------
+- Parameter ``filenameout`` in functions ``index_pats()`` and
+  ``index_pats_distributed()``, as it is unused.
+
 Fixed
 -----
 - OpenCL kernels and test data are also included in the built distribution (wheel), not

MANIFEST.in

@@ -11,4 +11,4 @@ include setup.cfg
 include setup.py
 
 recursive-include pyebsdindex *.png *.cl *.py
-recursive-include doc Makefile make.bat *.rst *.py *.ipynb
+recursive-include doc Makefile make.bat *.rst *.py *.ipynb *.png *.css

doc/_static/colormap_banners/create_colormap_banners.py

@@ -0,0 +1,24 @@
+# Colormap banners used on the doc landing page. Run from this directory
+# to place the banners in this directory, which is assumed in the docs.
+
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+
+
+plt.rcParams["backend"] = "agg"
+
+cmaps = [mpl.cm.plasma, mpl.cm.viridis]
+
+for i, cmap in enumerate(cmaps):
+    fig, ax = plt.subplots(figsize=(30, 1))
+    fig.subplots_adjust(bottom=0.5)
+    norm = mpl.colors.Normalize(vmin=5, vmax=10)
+    cbar = fig.colorbar(
+        mpl.cm.ScalarMappable(norm=norm, cmap=cmap),
+        cax=ax,
+        orientation="horizontal",
+    )
+    cbar.ax.set_axis_off()
+    cbar.ax.margins(0, 0)
+    fig.savefig(f"banner{i}.png", pad_inches=0, bbox_inches="tight")
+    i += 1

doc/_static/custom.css

@@ -0,0 +1,32 @@
+/* The following are adapted from Matplotlib's CSS file. */
+/* Hide "#" between thumbnail and caption showing upon hovering. */
+.sphx-glr-thumbcontainer a.headerlink {
+    visibility: hidden !important;
+}
+
+/* Hide notice linking to the bottom download section. */
+div.sphx-glr-download-link-note {
+    height: 0px;
+    visibility: hidden;
+}
+
+html[data-theme="dark"] .sphx-glr-thumbcontainer {
+    background-color: rgb(63, 63, 63);
+}
+
+/* Re-style the download button */
+div.sphx-glr-download a {
+    background-color: #E3F0F6;
+    background-image: none;
+    color: #11557c;
+    border: 0;
+}
+div.sphx-glr-download a:hover {
+    background-color: #BCD4DF;
+}
+/* The above are adapted from Matplotlib's CSS file. */
+
+.sphinx-codeautolink-a:hover {
+    text-decoration: underline;
+    color: #2A5ADF;
+}

doc/_templates/autosummary/base.rst

@@ -0,0 +1,5 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

doc/_templates/custom-attribute-template.rst

@@ -0,0 +1,9 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoproperty:: {{ objname }}
+
+.. Uncomment when using Sphinx-Gallery
+.. .. minigallery:: {{ module }}.{{ objname }}
+    :add-heading: Examples using ``{{ objname }}``

doc/_templates/custom-class-template.rst

@@ -0,0 +1,39 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+    {% block attributes %}
+    {% if attributes %}
+    .. rubric:: {{ _('Attributes') }}
+
+    .. autosummary::
+        :toctree:
+        :template: custom-attribute-template.rst
+        {% for item in attributes %}
+        {% if item.0 != item.upper().0 and item not in inherited_members %}
+        {{ name }}.{{ item }}
+        {% endif %}
+        {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block methods %}
+    {% if methods %}
+    .. rubric:: {{ _('Methods') }}
+
+    .. autosummary::
+        :toctree:
+        :template: custom-method-template.rst
+        {% for item in methods %}
+        {% if item != "__init__" and item not in inherited_members %}
+        {{ name }}.{{ item }}
+        {% endif %}
+        {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+.. Uncomment when using Sphinx-Gallery
+.. .. minigallery:: {{ module }}.{{ objname }}
+    :add-heading: Examples using ``{{ objname }}``

doc/_templates/custom-function-template.rst

@@ -0,0 +1,9 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. Uncomment when using Sphinx-Gallery
+.. .. minigallery:: {{ module }}.{{ objname }}
+    :add-heading: Examples using ``{{ objname }}``

doc/_templates/custom-method-template.rst

@@ -0,0 +1,9 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. automethod:: {{ objname }}
+
+.. Uncomment when using Sphinx-Gallery
+.. .. minigallery:: {{ module }}.{{ objname }}
+    :add-heading: Examples using ``{{ objname }}``

doc/_templates/custom-module-template.rst

@@ -0,0 +1,67 @@
+{{ name | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+    {% block attributes %}
+    {% if attributes %}
+    .. rubric:: Module Attributes
+
+    .. autosummary::
+        :toctree:
+        {% for item in attributes %}
+        {{ item }}
+        {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block functions %}
+    {% if functions %}
+    .. rubric:: {{ _('Functions') }}
+
+    .. autosummary::
+        :toctree:
+        :template: custom-function-template.rst
+        {% for item in functions %}
+        {{ item }}
+        {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block classes %}
+    {% if classes %}
+    .. rubric:: {{ _('Classes') }}
+
+    .. autosummary::
+        :toctree:
+        :template: custom-class-template.rst
+        {% for item in classes %}
+        {{ item }}
+        {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block exceptions %}
+    {% if exceptions %}
+    .. rubric:: {{ _('Exceptions') }}
+
+    .. autosummary::
+        :toctree:
+        {% for item in exceptions %}
+        {{ item }}
+        {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+    :toctree:
+    :template: custom-module-template.rst
+    :recursive:
+    {% for item in modules %}
+    {{ item }}
+    {%- endfor %}
+{% endif %}
+{% endblock %}