doc: switch from sphinx-panels (deprecated) to sphinx-design (#1161)

doc/sphinx/requirements.txt

@@ -2,7 +2,7 @@ altair>=4.1
 breathe>=4.30
 myst-parser[linkify]>=0.14.0
 sphinx-hoverxref>=0.3b1
-sphinx-panels
+sphinx-design
 sphinx>=4.3
 sphinx_rtd_theme
 sphinxcontrib-bibtex==2.4.2

doc/sphinx/source/conf.py

@@ -38,53 +38,53 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'altair.sphinxext.altairplot',
-    'breathe',
-    'hoverxref.extension',
-    'sphinx_panels',
-    'myst_parser',
-    'sphinx_rtd_theme',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.coverage',
-    'sphinx.ext.doctest',
-    'sphinx.ext.ifconfig',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.githubpages',
-    'sphinxcontrib.katex',
-    'sphinxcontrib.mermaid',  # still in beta; fails with latexpdf builder
-    'sphinx.ext.todo',
-    'sphinx.ext.viewcode',
-    'sphinxcontrib.bibtex',
-    'sphinxcontrib.rsvgconverter',
+    "altair.sphinxext.altairplot",
+    "breathe",
+    "hoverxref.extension",
+    "sphinx_design",
+    "myst_parser",
+    "sphinx_rtd_theme",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.coverage",
+    "sphinx.ext.doctest",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.githubpages",
+    "sphinxcontrib.katex",
+    "sphinxcontrib.mermaid",  # still in beta; fails with latexpdf builder
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "sphinxcontrib.bibtex",
+    "sphinxcontrib.rsvgconverter",
 ]
 
 # The following, if true, allows figures, tables and code-blocks to be
 # automatically numbered if they have a caption.
 numfig = True
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = 'libCEED'
-copyright = '2020, LLNL, University of Colorado, University of Illinois, University of Tennesee, and the authors'
-with open('../../../AUTHORS') as f:
+project = "libCEED"
+copyright = "2020, LLNL, University of Colorado, University of Illinois, University of Tennesee, and the authors"
+with open("../../../AUTHORS") as f:
     authorlist = f.readlines()
-author = ', '.join(authorlist)
+author = ", ".join(authorlist)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-with open('../../../ceed.pc.template') as f:
-    pkgconf_version = 'unknown'
+with open("../../../ceed.pc.template") as f:
+    pkgconf_version = "unknown"
     for line in f:
-        if line.startswith('Version:'):
-            pkgconf_version = line.partition(': ')[2]
+        if line.startswith("Version:"):
+            pkgconf_version = line.partition(": ")[2]
             break
 version = pkgconf_version
 # The full version, including alpha/beta/rc tags.
@@ -101,31 +101,31 @@
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
 exclude_patterns = [
-    'examples/README.md',
-    'examples/ceed/README.md',
-    'examples/fluids/README.md',
-    'examples/nek/README.md',
-    'examples/petsc/README.md',
-    'examples/solid/README.md',
+    "examples/README.md",
+    "examples/ceed/README.md",
+    "examples/fluids/README.md",
+    "examples/nek/README.md",
+    "examples/petsc/README.md",
+    "examples/solid/README.md",
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
 # sphinxcontrib-bibtex 2.0 requires listing all bibtex files here
 bibtex_bibfiles = [
-    'references.bib',
+    "references.bib",
 ]
 
 myst_enable_extensions = [
-    'deflist',
-    'dollarmath',
-    'html_image',
-    'linkify',
-    'colon_fence',
+    "deflist",
+    "dollarmath",
+    "html_image",
+    "linkify",
+    "colon_fence",
 ]
 
 myst_heading_anchors = 2
@@ -136,7 +136,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-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
@@ -155,17 +155,17 @@
 # This is required for the alabaster theme
 # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
 html_sidebars = {
-    '**': [
-        'relations.html',  # needs 'show_related': True theme option to display
-        'searchbox.html',
+    "**": [
+        "relations.html",  # needs 'show_related': True theme option to display
+        "searchbox.html",
     ]
 }
 
 # hoverxref options
 hoverxref_auto_ref = True
 hoverxref_mathjax = True
 hoverxref_role_types = {
-    'ref': 'modal',
+    "ref": "modal",
 }
 
 latex_macros = r"""
@@ -176,38 +176,36 @@
 
 # Translate LaTeX macros to KaTeX and add to options for HTML builder
 katex_macros = katex.latex_defs_to_katex_macros(latex_macros)
-katex_options = 'macros: {' + katex_macros + '}'
+katex_options = "macros: {" + katex_macros + "}"
 
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'libCEEDdoc'
+htmlhelp_basename = "libCEEDdoc"
 
 
 # -- Options for LaTeX output ---------------------------------------------
 
-latex_engine = 'lualatex'
+latex_engine = "lualatex"
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
-    'preamble': r"""
+    "preamble": r"""
 \usepackage{amscd}
 \newcommand\bm[1]{\symbf{#1}}
-""" + latex_macros,
-
+"""
+    + latex_macros,
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
-    'fontpkg': r"""
+    "fontpkg": r"""
 \usepackage[math-style=ISO,bold-style=ISO]{unicode-math}
 \setmainfont{TeX Gyre Pagella}
 \setmathfont{TeX Gyre Pagella Math}
@@ -216,27 +214,23 @@
 """,
 }
 
-latex_logo = '../../img/ceed-full-name-logo.PNG'
+latex_logo = "../../img/ceed-full-name-logo.PNG"
 
-latexauthorslist = r' \and '.join(authorlist)
+latexauthorslist = r" \and ".join(authorlist)
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'libCEED.tex', 'libCEED User Manual',
-     latexauthorslist, 'howto'),
+    (master_doc, "libCEED.tex", "libCEED User Manual", latexauthorslist, "howto"),
 ]
 
 
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'libceed', 'libCEED User Manual',
-     [author], 1)
-]
+man_pages = [(master_doc, "libceed", "libCEED User Manual", [author], 1)]
 
 
 # -- Options for Texinfo output -------------------------------------------
@@ -245,9 +239,15 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'libCEED', 'libCEED User Manual',
-     latexauthorslist, 'libCEED', 'Efficient implementations of finite element operators.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "libCEED",
+        "libCEED User Manual",
+        latexauthorslist,
+        "libCEED",
+        "Efficient implementations of finite element operators.",
+        "Miscellaneous",
+    ),
 ]
 
 
@@ -269,13 +269,13 @@
 # epub_uid = ''
 
 # A list of files that should not be packed into the epub file.
-epub_exclude_files = ['search.html']
+epub_exclude_files = ["search.html"]
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3', None),
-    'numpy': ('https://numpy.org/devdocs', None),
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/devdocs", None),
 }
 
 
@@ -287,10 +287,13 @@
 breathe_domain_by_extension = {"c": "c", "h": "c", "cpp": "cpp", "hpp": "cpp"}
 
 # Run Doxygen if building on Read The Docs
-rootdir = os.path.join(os.path.dirname(__file__),
-                       os.pardir, os.pardir, os.pardir)
-if os.environ.get('READTHEDOCS'):
-    subprocess.check_call(['doxygen', 'Doxyfile'], cwd=rootdir)
+rootdir = os.path.join(
+    os.path.dirname(__file__),
+    os.pardir,
+    os.pardir,
+    os.pardir)
+if os.environ.get("READTHEDOCS"):
+    subprocess.check_call(["doxygen", "Doxyfile"], cwd=rootdir)
 
 
 def mkdir_p(path):
@@ -302,18 +305,18 @@ def mkdir_p(path):
 
 # Copy example documentation from source tree
 try:
-    shutil.rmtree('examples')
+    shutil.rmtree("examples")
 except FileNotFoundError:
     pass
 for filename in glob.glob(os.path.join(
-        rootdir, 'examples/**/*.md'), recursive=True):
+        rootdir, "examples/**/*.md"), recursive=True):
     destdir = os.path.dirname(os.path.relpath(filename, rootdir))
     mkdir_p(destdir)
     shutil.copy2(filename, destdir)
-shutil.copy2(os.path.join(rootdir, 'README.md'), '.')
+shutil.copy2(os.path.join(rootdir, "README.md"), ".")
 
 for filename in glob.glob(os.path.join(
-        rootdir, 'examples/**/*.csv'), recursive=True):
+        rootdir, "examples/**/*.csv"), recursive=True):
     destdir = os.path.dirname(os.path.relpath(filename, rootdir))
     mkdir_p(destdir)
     shutil.copy2(filename, destdir)