Migrate docs to read-the-docs theme (hypre-space#803)

This switches the Sphinx documentation style to improve rendering of the "API" pages.

Author: rfalgout

.readthedocs.yml

@@ -10,6 +10,12 @@
 # Required
 version: 2
 
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: src/docs/usr-manual/conf.py
@@ -19,6 +25,5 @@ formats: all
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
-  version: 3.7
   install:
     - requirements: src/docs/usr-manual/requirements.txt

src/IJ_mv/HYPRE_IJ_mv.h

@@ -21,11 +21,9 @@ extern "C" {
 /**
  * @defgroup IJSystemInterface IJ System Interface
  *
- * This interface represents a linear-algebraic conceptual view of a
- * linear system.  The 'I' and 'J' in the name are meant to be
- * mnemonic for the traditional matrix notation A(I,J).
- *
- * @memo A linear-algebraic conceptual interface
+ * A linear-algebraic conceptual interface. This interface represents a
+ * linear-algebraic conceptual view of a linear system.  The 'I' and 'J' in the
+ * name are meant to be mnemonic for the traditional matrix notation A(I,J).
  *
  * @{
  **/

src/docs/README.md

@@ -102,3 +102,9 @@ Breathe:
 
 - https://breathe.readthedocs.io/en/latest/index.html
 
+## Some notes on customization
+
+After compilation, the CSS style files that control the HTML formatting will be
+in the folder `usr-manual-html/_static`.  To override any of these settings, add
+the appropriate lines to the file `usr-manual/_static/custom.css`.  Use the web
+to get information on CSS.

src/docs/ref-manual/conf.doxygen

@@ -1,6 +1,14 @@
-/* This file intentionally left blank. */
 
-/* Move Georgia first to get better rendering on Windows platforms */
+/* Classic theme customizations: left justify text alignment */
+/*
+div.body p, div.body dd, div.body li, div.body blockquote {
+    text-align: left;
+}
+*/
+
+/* Alabaster theme customizations: move Georgia first to get better rendering on
+   Windows platforms */
+/*
 body {
     font-family: Georgia, 'goudy old style', 'minion pro', 'bell mt', 'Hiragino Mincho Pro', serif;
     font-size: 17px;
@@ -9,3 +17,4 @@ body {
     margin: 0;
     padding: 0;
 }
+*/

src/docs/usr-manual/_static/custom.css

@@ -21,3 +21,19 @@ API
    api-sol-parcsr
    api-sol-krylov
    api-sol-eigen
+
+.. Add blank lines to help with navigation pane formatting
+|
+|
+|
+|
+|
+|
+|
+|
+|
+|
+|
+|
+|
+|

src/docs/usr-manual/bw-hypre-nwords.512.png

@@ -11,20 +11,18 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import os
+import sys
+import subprocess
 
 # Alabaster
-import alabaster
+#import alabaster
 
 # Read the docs
-#import sphinx_rtd_theme
-
-import subprocess
-
-read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
-
-if read_the_docs_build:
+import sphinx_rtd_theme
 
+# Run doxygen if building on Read the Docs
+if os.environ.get('READTHEDOCS'):
     subprocess.call('cd ../ref-manual; doxygen conf.doxygen', shell=True)
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -40,7 +38,15 @@
 # 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.pngmath']
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.mathjax', 'breathe']
+extensions = [
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.viewcode',
+    'breathe',
+    'sphinx_rtd_theme',
+]
 breathe_projects = { 'hypre': '../ref-manual/xml' }
 
 # Add any paths that contain templates here, relative to this directory.
@@ -80,7 +86,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = []
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -107,39 +113,42 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#html_theme = 'default'
+
+# Classic
+#html_theme = 'classic'
 
 # Alabaster
-html_theme = 'alabaster'
+#html_theme = 'alabaster'
 
 # Read the docs
-#html_theme = 'sphinx_rtd_theme'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
 
-# Alabaster
-html_theme_options = {
-    'page_width': '1200px',
-    'sidebar_width': '300px',
-    'fixed_sidebar': 'true',
-}
+# Classic
+#html_theme_options = {
+#    'body_min_width': '900px',
+#    'sidebarwidth': '300px',
+#    'stickysidebar': 'true',
+#}
 
-# Read the docs
+# Alabaster
 #html_theme_options = {
-#    'typekit_id': 'hiw1hhg',
+#    'page_width': '1200px',
+#    'sidebar_width': '300px',
+#    'fixed_sidebar': 'true',
 #}
 
+# Read the docs
+html_theme_options = {
+}
+
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
 
 # Alabaster
-html_theme_path = [alabaster.get_path()]
-
-# Read the docs
-#html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+#html_theme_path = [alabaster.get_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -150,7 +159,8 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+#html_logo = 'hypre-nwords.512.png'
+html_logo = 'bw-hypre-nwords.512.png'  # Black/white looks better with rtd theme
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -161,6 +171,7 @@
 # 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']
+html_css_files = ["custom.css"]
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -171,18 +182,25 @@
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+
+# Classic
+#html_sidebars = {
+#    '**': [
+#        'globaltoc.html',
+#        'relations.html',
+#        'searchbox.html',
+#    ]
+#}
 
 # Alabaster
-html_sidebars = {
-    '**': [
-        'about.html',
-        'navigation.html',
-        'relations.html',
-        'searchbox.html',
-        'donate.html',
-    ]
-}
+#html_sidebars = {
+#    '**': [
+#        'about.html',
+#        'navigation.html',
+#        'relations.html',
+#        'searchbox.html',
+#    ]
+#}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.