Revive the HEXRD readthedocs documentation

A lot has changed since the documentation was last generated 6 years ago, including sphinx and its extensions. Automatic documentation is now simpler, so a lot of files previously present were no longer needed and are deleted in this commit. The process of generating the documentation is now quite simple. See the `docs/README.md` file for more info. This overall seems to generate the documentation correctly. Signed-off-by: Patrick Avery <patrick.avery@kitware.com>
HEXRD · Aug 21, 2023 · 1e6dcc2 · 1e6dcc2
1 parent d1de88a
commit 1e6dcc2
Show file tree

Hide file tree

Showing 20 changed files with 115 additions and 1,202 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,19 @@
+version: 2
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: '3.10'
+  jobs:
+    pre_build:
+      # Run the apidoc command to generate the initial module files
+      - docs/run_apidoc.sh
diff --git a/docs/Makefile b/docs/Makefile
@@ -5,8 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
+SOURCEDIR     = source
+BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
 help:

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,14 @@
+HEXRD Documentation
+===================
+
+The HEXRD documentation utilizes sphinx along with sphinx-apidoc to
+automatically generate documentation for all of the HEXRD packages.
+
+Manually created files may be added as well in either RST or Markdown format.
+See the files in `source/users` as an example.
+
+To build the documentation locally, first install the dependencies in the
+`requirements.txt` file, then run the `run_sphinx.sh` script. The HTML files
+should be automatically generated and placed inside `build/html`. Open up
+the `build/html/index.html` file in a web browser to view the generated
+content.
diff --git a/docs/README.rst b/docs/README.rst
diff --git a/docs/autogen_api.py b/docs/autogen_api.py
diff --git a/docs/build.rst b/docs/build.rst
diff --git a/docs/conf.py b/docs/conf.py
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,8 @@
+# Pin sphinx to be less than 7 until new sphinx-rtd-theme comes out: https://github.com/readthedocs/readthedocs.org/issues/10279#issuecomment-1529988748
+sphinx<7
+pygments
+sphinx-rtd-theme
+myst-parser
+
+# We need matplotlib for some of the documentation
+matplotlib
diff --git a/docs/run_apidoc.sh b/docs/run_apidoc.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+SCRIPT_DIR=`dirname "$0"`
+pushd .
+cd $SCRIPT_DIR
+
+# sphinx-apidoc argument explanation:
+# -d 1        - only use a depth of one for table of contents (TOC)
+# -T          - don't generate the modules.rst TOC file
+# -e          - put documentation for each module on its own page
+# -f          - overwrite previously existing files
+# -o source/  - place the output files into the source directory
+# ../hexrd    - the path to the root source directory
+# Extra arguments at the end are exclude patterns
+sphinx-apidoc -d 1 -T -e -f -o source/ ../hexrd
+
+popd