Add SVG converter, fix PDF rendering on ReadTheDocs (#407)

### What kind of change does this PR introduce?

* Adds an SVG converter to the PDF generating LaTeX dependencies

### Does this PR introduce a breaking change?

It should not.

### Other information:

What's going on here?

Some changes to the LaTeX engine on ReadTheDocs have been causing the
SVG files referenced in the README.rst to be rendered as individual PDF
files. I'm not certain why that is happening, but it was causing the
`latest` and `stable` documentation builds to fail. This PR makes it so
that instead of the README.rst being referenced directly by sphinx,
instead it is copied and patched to not render the badges when building
for PDF. This has fixed the issue.

.gitignore

@@ -73,6 +73,7 @@ docs/.jupyter_cache
 docs/apidoc/modules.rst
 docs/apidoc/ravenpy*.rst
 docs/jupyter_execute
+docs/readme.rst
 
 # PyBuilder
 target/

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)
 --------------------

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

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

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",
     ),
 ]

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

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 = [