Merge pull request #113 from IMMM-SFA/bugfix/sphinx-version-error

fix failing doc build
IMMM-SFA · Nov 13, 2024 · 1cde4dc · 1cde4dc
2 parents d553647 + b89d593
commit 1cde4dc
Show file tree

Hide file tree

Showing 4 changed files with 74 additions and 68 deletions.
diff --git a/README.md b/README.md
@@ -89,7 +89,7 @@ Currently, demand input is read monthly but will also pad to the closest time in
 Efforts are under way for more robust demand handling.
 
 Dams/reservoirs require four different input files: the physical characteristics, the average monthly flow expected during the simulation period, the average monthly demand expected during the simulation period, and a database mapping each GRanD ID to grid cell IDs allowed to extract water from it.
-These dam/reservoir input files can be generated from raw GRanD data, raw elevation data, and raw ISTARF data using the [provided utility](mosartwmpy/utilities/CREATE_GRAND_PARAMETERS.md).
+These dam/reservoir input files can be generated from raw GRanD data, raw elevation data, and raw ISTARF data using the [provided utility](/mosartwmpy/utilities/CREATE_GRAND_PARAMETERS.md).
 The best way to understand the expected format of the input files is to examine the sample inputs provided by the download utility: `python -m mosartwmpy.download`.
 
 #### multi-file input

diff --git a/docs/conf.py b/docs/conf.py
@@ -12,17 +12,21 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../'))
+
+import mosartwmpy
+
+
+sys.path.insert(0, os.path.abspath("../"))
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'mosartwmpy'
-copyright = '2021, Battelle Memorial Institute'
-author = 'Travis B. Thurber'
+project = "mosartwmpy"
+copyright = "2021, Battelle Memorial Institute"
+author = "Travis B. Thurber"
 
 # The full version, including alpha/beta/rc tags
-release = 'latest'
+release = "latest"
 
 
 # -- General configuration ---------------------------------------------------
@@ -31,37 +35,36 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'nbsphinx',
-    'recommonmark',
-    'sphinx.ext.napoleon',
-    'sphinx.ext.autodoc',
-    'sphinx_panels',
-    'sphinx_rtd_theme'
+    "nbsphinx",
+    "recommonmark",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx_design",
+    "sphinx_rtd_theme",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+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']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+autodoc_default_options = {"ignore-module-all": True}
 
 # -- Options for HTML output -------------------------------------------------
 
 # 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"
 
 # 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']
-html_css_files = ['style.css']
+html_static_path = ["_static"]
+html_css_files = ["style.css"]
 
 panels_delimiters = (r"^\>{3,}$", r"^\^{3,}$", r"^\+{3,}$")
-
-import mosartwmpy
 version = str(mosartwmpy.__version__)
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,6 +1,6 @@
 :notoc:
 
-.. mosartwmpy documentation master file, created by
+.. mosartwmpy documentation master file
 
 .. module:: mosartwmpy
 
@@ -11,72 +11,74 @@ mosartwmpy documentation
 **Date**: |today| **Version**: |version|
 
 **Useful links**:
-`Source Repository <https://github.com/immm-sfa/mosartwmpy>`__ |
-`Issues & Ideas <https://github.com/immm-sfa/mosartwmpy/issues>`__
+`Source Repository <https://github.com/immm-sfa/mosartwmpy>`_
+`Issues & Ideas <https://github.com/immm-sfa/mosartwmpy/issues>`_
 
 `mosartwmpy` is a Python translation of MOSART-WM, a water routing and reservoir management model written in Fortran.
 
 
-.. panels::
-    :card: + intro-card text-center
-    :column: col-lg-6 col-md-6 col-sm-6 col-xs-12 d-flex
+.. grid:: 2
+    :gutter: 5
 
-    >>>
-    :img-top: _static/cognitive.svg
+    .. grid-item-card:: Getting started
+        :img-top: _static/cognitive.svg
+        :class-img-top: sd-px-5, sd-py-5
+        :text-align: center
 
-    Getting started
-    ^^^
+        Get to know the *mosartwmpy* model.
 
-    Get to know the *mosartwmpy* model.
+        +++
+        .. button-ref:: README
+                :click-parent:
+                :color: primary
+                :expand:
 
-    +++
-    .. link-button:: README
-            :type: ref
-            :text: Getting started
-            :classes: btn-block btn-secondary stretched-link
+                Getting started
 
-    >>>
-    :img-top: _static/education.svg
+    .. grid-item-card:: Tutorial
+        :img-top: _static/education.svg
+        :class-img-top: sd-px-5, sd-py-5
+        :text-align: center
 
-    Tutorial
-    ^^^
+        Follow along with this Jupyter notebook to learn the ropes of *mosartwmpy*.
 
-    Follow along with this Jupyter notebook to learn the ropes of *mosartwmpy*.
+        +++
+        .. button-ref:: tutorial
+                :click-parent:
+                :color: primary
+                :expand:
 
-    +++
-    .. link-button:: tutorial
-            :type: ref
-            :text: Tutorial
-            :classes: btn-block btn-secondary stretched-link
+                Tutorial
 
-    >>>
-    :img-top: _static/soccer.svg
+    .. grid-item-card:: Tips & tricks
+        :img-top: _static/soccer.svg
+        :class-img-top: sd-px-5, sd-py-5
+        :text-align: center
 
-    Tips & tricks
-    ^^^
+        Learn about ways to manage Python virtual environments.
 
-    Learn about ways to manage Python virtual environments.
+        +++
+        .. button-ref:: virtualenv
+                :click-parent:
+                :color: primary
+                :expand:
 
-    +++
-    .. link-button:: virtualenv
-            :type: ref
-            :text: Virtual environments
-            :classes: btn-block btn-secondary stretched-link
+                Virtual environments
 
-    >>>
-    :img-top: _static/api.svg
+    .. grid-item-card:: API reference
+        :img-top: _static/api.svg
+        :class-img-top: sd-px-5, sd-py-5
+        :text-align: center
 
-    API reference
-    ^^^
+        A detailed description of the *mosartwmpy* API.
 
-    A detailed description of the *mosartwmpy* API.
-
-    +++
-    .. link-button:: mosartwmpy
-            :type: ref
-            :text: API
-            :classes: btn-block btn-secondary stretched-link
+        +++
+        .. button-ref:: mosartwmpy
+                :click-parent:
+                :color: primary
+                :expand:
 
+                API
 
 .. toctree::
     :maxdepth: 1

diff --git a/setup.py b/setup.py
@@ -59,11 +59,12 @@ def readme():
     extras_require={
         "dev": [
             "build>=0.7.0",
+            "ipython",
             "nbsphinx>=0.8.7",
             "recommonmark>=0.7.1",
             "setuptools>=58.3.0",
-            "sphinx==4.2.0",
-            "sphinx-panels>=0.6.0",
+            "sphinx>=5",
+            "sphinx_design",
             "sphinx-rtd-theme>=1.0.0",
             "twine>=3.4.2",
             "pre-commit",