Add online documentation via Read the Docs (#13)

* Improve installation instructions for Windows (pyopencl) Signed-off-by: Håkon Wiik Ånes <[email protected]> * Add status badge to README for build action Signed-off-by: Håkon Wiik Ånes <[email protected]> * Increase absolute tolerance of PC test to account for randomness Signed-off-by: Håkon Wiik Ånes <[email protected]> * Add explanation of experimental parameters for simulated Al pattern Signed-off-by: Håkon Wiik Ånes <[email protected]> * Add contributing guide explaining tests and CI Signed-off-by: Håkon Wiik Ånes <[email protected]> * Install wheel package to speed up dependency installation on macOS Signed-off-by: Håkon Wiik Ånes <[email protected]> * Add docstrings to public API classes, methods and functions Signed-off-by: Håkon Wiik Ånes <[email protected]> * Update contributing guide with info on building the docs Signed-off-by: Håkon Wiik Ånes <[email protected]> * Add docs badge to README, ensure notebooks display nicely in TOC tree Signed-off-by: Håkon Wiik Ånes <[email protected]> * Add [doc] and [dev] (doc + tests) extra options to setup.py Signed-off-by: Håkon Wiik Ånes <[email protected]> * Add Read the Docs files for building documentation online Signed-off-by: Håkon Wiik Ånes <[email protected]> * Remove wheel package because macOS build fails with it Signed-off-by: Håkon Wiik Ånes <[email protected]> * Try to fix displaying of ebsd_index module in reference Signed-off-by: Håkon Wiik Ånes <[email protected]> * Add link to docs in README, add note to contributing guide Signed-off-by: Håkon Wiik Ånes <[email protected]>
USNavalResearchLaboratory · Feb 18, 2022 · 17f4c7b · 17f4c7b
1 parent ca983d6
commit 17f4c7b
Show file tree

Hide file tree

Showing 20 changed files with 862 additions and 298 deletions.
diff --git a/.gitignore b/.gitignore
@@ -18,4 +18,7 @@ report.log
 *.code-workspace
 
 # Line coverage
-.coverage
+.coverage
+
+# Sphinx
+doc/_build
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -0,0 +1,97 @@
+============
+Contributing
+============
+
+PyEBSDIndex is a community maintained project. We welcome contributions in the form of
+bug reports, documentation, code, feature requests, and more. The source code is hosted
+on `GitHub <https://github.com/USNavalResearchLaboratory/PyEBSDIndex>`_. This guide
+provides some tips on how to build documentation and run tests when contributing.
+
+Building and writing documentation
+==================================
+
+We use `Sphinx <https://www.sphinx-doc.org/en/master/>`_ for documenting functionality.
+Install necessary dependencies to build the documentation::
+
+    pip install --editable .[doc]
+
+Then, build the documentation from the ``doc`` directory::
+
+    cd doc
+    make html
+
+The documentation's HTML pages are built in the ``doc/build/html`` directory 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/pyebsdindex/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.
+- Refer to our reference with this general MD
+  ``[pcopt.optimize()](../reference.rst#pyebsdindex.pcopt.optimize)``. Remember to add
+  the parentheses ``()`` for functions and methods.
+- Reference external references via standard MD like
+  ``[Signal2D](http://hyperspy.org/hyperspy-doc/current/api/hyperspy._signals.signal2d.html)``.
+- The Sphinx gallery thumbnail used for a notebook is set by adding the
+  ``nbsphinx-thumbnail`` tag to a code cell with an image output. The notebook must be
+  added to the gallery in the `index.rst` to be included in the documentation pages.
+- The Furo Sphinx theme displays the documentation in a light or dark theme, depending
+  on the browser/OS setting. It is important to make sure the documentation is readable
+  with both themes. This means displaying all figures with a white background for axes
+  labels and ticks and figure titles etc. to be readable.
+
+Running and writing tests
+=========================
+
+Some functionality in PyEBSDIndex is tested via the `pytest <https://docs.pytest.org>`_
+framework. The tests reside in the ``pyebsdindex/tests`` directory. Tests are short
+methods that call functions in PyEBSDIndex and compare resulting output values with
+known answers. Install necessary dependencies to run the tests::
+
+    pip install --editable .[tests]
+
+Some useful `fixtures <https://docs.pytest.org/en/latest/fixture.html>`_, like a
+dynamically simulated Al pattern, are available in the ``conftest.py`` file.
+
+To run the tests::
+
+    pytest --cov --pyargs pyebsdindex
+
+The ``--cov`` flag makes `coverage.py <https://coverage.readthedocs.io/en/latest/>`_
+print a nice report in the terminal. For an even nicer presentation, you can use
+``coverage.py`` directly::
+
+    coverage html
+
+Then, you can open the created ``htmlcov/index.html`` in the browser and inspect the
+coverage in more detail.
+
+To run only a specific test function or class, .e.g the ``TestEBSDIndexer`` class::
+
+    pytest -k TestEBSDIndexer
+
+This is useful when you only want to run a specific test and not the full test suite,
+e.g. when you're creating or updating a test. But remember to run the full test suite
+before pushing!
+
+Tips for writing tests of Numba decorated functions:
+
+- A Numba decorated function ``numba_func()`` is only covered if it is called in the
+  test as ``numba_func.py_func()``.
+- Always test a Numba decorated function calling ``numba_func()`` directly, in addition
+  to ``numba_func.py_func()``, because the machine code function might give different
+  results on different OS with the same Python code.
+
+Continuous integration (CI)
+===========================
+
+We use `GitHub Actions
+<https://github.com/USNavalResearchLaboratory/PyEBSDIndex/actions>`_ to ensure that
+PyEBSDIndex can be installed on macOS and Linux (Ubuntu). After a successful
+installation of the package, the CI server runs the tests. Add "[skip ci]" to a commit
+message to skip this workflow on any commit to a pull request.
diff --git a/README.md b/README.md
@@ -2,6 +2,9 @@
 
 Python based tool for Hough/Radon based EBSD orientation indexing.
 
+[![Build status](https://github.com/USNavalResearchLaboratory/PyEBSDIndex/actions/workflows/build.yml/badge.svg)](https://github.com/USNavalResearchLaboratory/PyEBSDIndex/actions/workflows/build.yml)
+[![Documentation status](https://readthedocs.org/projects/pyebsdindex/badge/?version=latest)](https://pyebsdindex.readthedocs.io/en/latest/)
+
 The pattern processing is based on a GPU pipeline, and is based on the work of S. I.
 Wright and B. L. Adams. Metallurgical Transactions A-Physical Metallurgy and Materials
 Science, 23(3):759–767, 1992, and N. Krieger Lassen. Automated Determination of Crystal
@@ -16,12 +19,18 @@ Additionally NLPAR pattern processing is included (original distribution
 [NLPAR](https://github.com/USNavalResearchLaboratory/NLPAR); P. T. Brewick, S. I.
 Wright, and D. J. Rowenhorst. Ultramicroscopy, 200:50–61, May 2019.).
 
+Documentation with a user guide, API reference, changelog, and contributing guide is
+available at https://pyebsdindex.readthedocs.io.
+
 ## Installation
 
-The package can only be installed from source at the moment:
+The package can only be installed from source at the moment. There is an issue with
+installing `pyopencl` from `pip` on Windows, so this has to be installed from `conda`
+before installing `PyEBSDIndex`:
 
 ```bash
+conda install pyopencl --channel conda-forge  # Only required on Windows
 git clone https://github.com/USNavalResearchLaboratory/PyEBSDIndex
 cd PyEBSDIndex
 pip install --editable .
-```
+```
diff --git a/doc/Makefile b/doc/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/NLPAR_demo.ipynb b/doc/NLPAR_demo.ipynb
@@ -5,7 +5,7 @@
    "id": "8041bd4f-d7ae-402c-968b-0a3fb76784b6",
    "metadata": {},
    "source": [
-    "## NLPAR Examples"
+    "# NLPAR Examples"
    ]
   },
   {
@@ -213,7 +213,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.12"
+   "version": "3.9.10"
   }
  },
  "nbformat": 4,

diff --git a/doc/changelog.rst b/doc/changelog.rst
@@ -0,0 +1,2 @@
+.. include:: ../CHANGELOG.rst
+.. This is a stub, see the top level CHANGELOG.rst file for the changelog.
diff --git a/doc/conf.py b/doc/conf.py
@@ -0,0 +1,72 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a
+# full list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+from datetime import datetime
+import os
+import sys
+
+from pyebsdindex import __author__, __version__
+
+
+# If extensions (or modules to document with autodoc) are in another
+# directory, add these directories to sys.path here. If the directory is
+# relative to the documentation root, use os.path.abspath to make it
+# absolute, like shown here.
+sys.path.insert(0, os.path.abspath('.'))
+
+project = "PyEBSDIndex"
+copyright = f"{datetime.now().year}, {__author__}"
+author = __author__
+version = __version__
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx_copybutton",
+    "sphinx_gallery.load_style",
+    "nbsphinx",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+# templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# The theme to use for HTML and HTML Help pages.  See the documentation
+# for a list of builtin themes.
+#
+html_theme = "furo"
+
+# Add any paths that contain custom static files (such as style sheets
+# here, relative to this directory. They are copied after the builtin
+# static files, so a file named "default.css" will overwrite the builtin
+# "default.css".
+# html_static_path = ['_static']
+
+# Create links to references within the documentation to these packages
+intersphinx_mapping = {
+    "h5py": ("https://docs.h5py.org/en/stable", None),
+    "matplotlib": ("https://matplotlib.org", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "python": ("https://docs.python.org/3", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
+}
+
+# -- nbsphinx configuration --------------------------------------------
+nbsphinx_execute = "auto"
+nbsphinx_execute_arguments = [
+    "--InlineBackend.rc=figure.facecolor='w'",
+    "--InlineBackend.rc=font.size=15",
+]
diff --git a/doc/contributing.rst b/doc/contributing.rst
@@ -0,0 +1,2 @@
+.. include:: ../CONTRIBUTING.rst
+.. This is a stub, see the top level CONTRIBUTING.rst file for the contributing guide.
diff --git a/doc/ebsd_index_demo.ipynb b/doc/ebsd_index_demo.ipynb
@@ -1,5 +1,13 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "496b84d4-54ca-47c7-9a47-0709acffd06b",
+   "metadata": {},
+   "source": [
+    "# Hough indexing"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
@@ -189,7 +197,11 @@
    "cell_type": "code",
    "execution_count": 6,
    "id": "5fa77d67-0581-42fc-80c2-ae37489256f3",
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "nbsphinx-thumbnail"
+    ]
+   },
    "outputs": [
     {
      "data": {
@@ -778,7 +790,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.12"
+   "version": "3.9.10"
   }
  },
  "nbformat": 4,

diff --git a/doc/index.rst b/doc/index.rst
@@ -0,0 +1,58 @@
+===========
+PyEBSDIndex
+===========
+
+Python based tool for Hough/Radon based EBSD orientation indexing.
+
+.. GitHub Actions
+.. image:: https://github.com/USNavalResearchLaboratory/PyEBSDIndex/actions/workflows/build.yml/badge.svg
+    :target: https://github.com/USNavalResearchLaboratory/PyEBSDIndex/actions
+    :alt: Build status
+
+.. Read the Docs
+.. image:: https://readthedocs.org/projects/pyebsdindex/badge/?version=latest
+    :target: https://pyebsdindex.readthedocs.io/en/latest/
+    :alt: Documentation status
+
+The pattern processing is based on a GPU pipeline, and is based on the work of S. I.
+Wright and B. L. Adams. Metallurgical Transactions A-Physical Metallurgy and Materials
+Science, 23(3):759–767, 1992, and N. Krieger Lassen. Automated Determination of Crystal
+Orientations from Electron Backscattering Patterns. PhD thesis, The Technical University
+of Denmark, 1994.
+
+The band indexing is achieved through triplet voting using the methods outlined by A.
+Morawiec. Acta Crystallographica Section A Foundations and Advances, 76(6):719–734,
+2020.
+
+Additionally NLPAR pattern processing is included (original distribution
+`NLPAR <https://github.com/USNavalResearchLaboratory/NLPAR>`_; P. T. Brewick, S. I.
+Wright, and D. J. Rowenhorst. Ultramicroscopy, 200:50–61, May 2019.).
+
+Installation
+============
+
+The package can only be installed from source at the moment. There is an issue with
+installing `pyopencl` from `pip` on Windows, so this has to be installed from `conda`
+before installing `PyEBSDIndex`::
+
+    conda install pyopencl --channel conda-forge  # Only required on Windows
+    git clone https://github.com/USNavalResearchLaboratory/PyEBSDIndex
+    cd PyEBSDIndex
+    pip install --editable .
+
+User guide
+==========
+
+.. nbgallery::
+    :caption: User guide
+
+    ebsd_index_demo.ipynb
+    NLPAR_demo.ipynb
+
+.. toctree::
+    :hidden:
+    :caption: Help & reference
+
+    reference.rst
+    changelog.rst
+    contributing.rst
diff --git a/doc/make.bat b/doc/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		.. include:: ../CHANGELOG.rst
		.. This is a stub, see the top level CHANGELOG.rst file for the changelog.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		.. include:: ../CONTRIBUTING.rst
		.. This is a stub, see the top level CONTRIBUTING.rst file for the contributing guide.