diff --git a/.gitignore b/.gitignore index 8bec6832..a8f33d97 100644 --- a/.gitignore +++ b/.gitignore @@ -73,6 +73,7 @@ docs/.jupyter_cache docs/apidoc/modules.rst docs/apidoc/ravenpy*.rst docs/jupyter_execute +docs/readme.rst # PyBuilder target/ diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 923ab2c0..096136c5 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -20,6 +20,7 @@ Internal changes * Added `setuptools` to the `gis` build recipe to ensure that the `gdal` bindings are built successfully. (PR #400) * Modified the sub-basin and channel profile extraction functions to correctly set the river length to zero and set default values for reach attributes in sub-basins with no channel routing (i.e., sub-basins with lakes or headwater basins). (issue #354, PR #401) * Improved the HBV-EC emulator by adding parameter information (name, definition, and Raven default values), fixed the variable name for the adiabatic temperature lapse rate, and added an alias for rain snow fraction to match other emulators. (PR #404 and #408) +* Modified the `sphinx` configuration to better support SVG and to remove incompatible elements from the PDF build. (PR #407) v0.15.0 (2024-06-20) -------------------- diff --git a/README.rst b/README.rst index 0d80fde6..c57818f0 100644 --- a/README.rst +++ b/README.rst @@ -14,6 +14,7 @@ RavenPy | Development Status | |status| |build| |coveralls| | +----------------------------+-----------------------------------------------------+ + A Python wrapper to setup and run the hydrologic modelling framework Raven_. * Free software: MIT license diff --git a/docs/Makefile b/docs/Makefile index 3edd182b..24cda968 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,9 +1,10 @@ # Minimal makefile for Sphinx documentation # -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = python -msphinx +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build SPHINXPROJ = ravenpy SOURCEDIR = . BUILDDIR = _build diff --git a/docs/conf.py b/docs/conf.py index 4b0214a2..14f5aa7d 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,11 +20,35 @@ import os import sys from datetime import date +from pathlib import Path sys.path.insert(0, os.path.abspath("..")) import ravenpy # noqa: E402 +# -- Workarounds ------------------------------------------------------ + +def rebuild_readme(): + """Rebuild the readme.rst file from the top-level README.rst file. + + This is a workaround to remove the badge table found in the README.rst + when building the docs specifically for latex/pdf output. + """ + + with Path("../README.rst").open(encoding="utf-8") as f: + readme = f.read() + + # Remove the badge table + readme = readme.replace("=======\nRavenPy\n=======", "=======\nRavenPy\n=======\n\n.. only:: not latex") + readme = readme.replace("\n+-", "\n +-") + readme = readme.replace("\n|", "\n |") + + with Path("readme.rst").open("w", encoding="utf-8") as f: + f.write(readme) + +rebuild_readme() + + # -- General configuration --------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -42,11 +66,11 @@ "sphinx.ext.todo", "sphinx.ext.viewcode", "IPython.sphinxext.ipython_console_highlighting", - # "nbsphinx", "myst_nb", "sphinx_click", "sphinx_codeautolink", "sphinx_copybutton", + "sphinxcontrib.cairosvgconverter", # "sphinxcontrib.autodoc_pydantic", # FIXME: Does not seem to be compatible with RavenPy codebase. ] @@ -126,7 +150,7 @@ # The suffix(es) of source filenames. # You can specify multiple suffix as a dictionary of suffix: filetype -source_suffix = {'.rst': 'restructuredtext'} +source_suffix = {".rst": "restructuredtext"} # The master toctree document. master_doc = "index" @@ -208,16 +232,16 @@ latex_elements = { # The paper size ('letterpaper' or 'a4paper'). # - # 'papersize': 'letterpaper', + 'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). # - # 'pointsize': '10pt', + 'pointsize': '10pt', # Additional stuff for the LaTeX preamble. # - # 'preamble': '', + 'preamble': '', # Latex figure (float) alignment # - # 'figure_align': 'htbp', + 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples @@ -245,7 +269,7 @@ "RavenPy Documentation", author, "ravenpy", - "One line description of project.", + "A Python wrapper to setup and run the hydrologic modelling framework Raven.", "Miscellaneous", ), ] diff --git a/docs/readme.rst b/docs/readme.rst deleted file mode 100644 index 72a33558..00000000 --- a/docs/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../README.rst diff --git a/environment-rtd.yml b/environment-rtd.yml index 4bc8d07b..8aac010c 100644 --- a/environment-rtd.yml +++ b/environment-rtd.yml @@ -3,9 +3,10 @@ channels: - conda-forge - defaults dependencies: - - python >=3.9,<3.10 # fixed to reduce solver time + - python >=3.10,<3.11 # fixed to reduce solver time - raven-hydro >=0.3.1,<1.0 - autodoc-pydantic + - cairosvg - click >=8.0.0 # - clisops # mocked - gdal >=3.1 @@ -33,7 +34,7 @@ dependencies: - sphinx-codeautolink - sphinx-copybutton - sphinx-rtd-theme >=1.0 - - sphinxcontrib-napoleon + - sphinxcontrib-svg2pdfconverter - typing_extensions - wheel # - xarray # mocked diff --git a/pyproject.toml b/pyproject.toml index 06b3189d..209dea4c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -95,6 +95,7 @@ dev = [ docs = [ "autodoc-pydantic", "birdhouse-birdy", + "cairosvg", "cartopy", "clisops", "gcsfs", @@ -123,6 +124,7 @@ docs = [ "sphinx-codeautolink", "sphinx-copybutton", "sphinx-rtd-theme >=1.0", + "sphinxcontrib-svg2pdfconverter >=1.2.3", "xesmf" ] gis = [