From b89d593cb37442259b74904be93957c4d776fa2f Mon Sep 17 00:00:00 2001 From: erexer <13180883+erexer@users.noreply.github.com> Date: Wed, 13 Nov 2024 08:24:11 -0800 Subject: [PATCH] fix failing doc build --- README.md | 2 +- docs/conf.py | 39 ++++++++++---------- docs/index.rst | 96 ++++++++++++++++++++++++++------------------------ setup.py | 5 +-- 4 files changed, 74 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 19a66ed..5c15b31 100644 --- 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 index e9ea4aa..228e17b 100644 --- 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 index cbe383a..276d8b7 100644 --- 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 `__ | -`Issues & Ideas `__ +`Source Repository `_ +`Issues & Ideas `_ `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 index 43c069b..247593d 100644 --- 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",