feat: add latex and plot style utilities (#132)

* move figspec and latex utilities from mf6 examples repo
* add matplotlib as optional dependency
* update readme

.github/workflows/ci.yml

@@ -132,7 +132,7 @@ jobs:
         working-directory: modflow-devtools
         run: |
           pip install .
-          pip install ".[test]"
+          pip install ".[test, optional]"
       
       - name: Cache modflow6 examples
         id: cache-examples

README.md

@@ -29,9 +29,13 @@ Python development tools for MODFLOW 6.
 
 ## Use cases
 
-This is a small toolkit for developing MODFLOW 6, FloPy, and related projects. It includes standalone utilities and optional [Pytest](https://github.com/pytest-dev/pytest) extensions.
+This is a small toolkit for developing MODFLOW 6, FloPy, and related projects. It includes standalone utilities and optional [Pytest](https://github.com/pytest-dev/pytest) and [Matplotlib](https://matplotlib.org/stable/) extensions.
 
-The former include a very minimal GitHub API client for retrieving release information and downloading assets, a `ZipFile` subclass that [preserves file permissions](https://stackoverflow.com/questions/39296101/python-zipfile-removes-execute-permissions-from-binaries) (workaround for [Python #15795](https://bugs.python.org/issue15795)), and other release/distribution-related tools.
+Utilities include:
+
+* a minimal GitHub API client for retrieving release information and downloading assets
+* a `ZipFile` subclass that [preserves file permissions](https://stackoverflow.com/questions/39296101/python-zipfile-removes-execute-permissions-from-binaries) (workaround for [Python #15795](https://bugs.python.org/issue15795))
+* other release/distribution-related tools
 
 Pytest features include:
 
@@ -46,6 +50,8 @@ Pytest features include:
   - `MODFLOW-USGS/modflow6-testmodels`
   - `MODFLOW-USGS/modflow6-largetestmodels`
 
+Matplotlib styles are provided in the `modflow_devtools.figspecs` module.
+
 ## Requirements
 
 Python3.8+, dependency-free, but pairs well with `pytest` and select plugins, e.g.

autotest/test_figspec.py

@@ -0,0 +1,5 @@
+from modflow_devtools.figspec import USGSFigure
+
+
+def test_usgs_figure():
+    fig = USGSFigure()

docs/index.rst

@@ -29,6 +29,8 @@ The `modflow-devtools` package provides a set of tools for developing and testin
    :caption: Miscellaneous
 
    md/download.md
+   md/figspec.md
+   md/latex.md
    md/ostags.md
    md/zip.md
    md/timed.md

docs/md/figspec.md

@@ -0,0 +1,33 @@
+# Plot styles
+
+Matplotlib is an optional dependency, installable via e.g. `pip install modflow_devtools[optional]`.
+
+## `USGSFigure`
+
+A convenience class `modflow_devtools.figspec.USGSFigure` is provided to create figures with the default USGS style sheet. For instance:
+
+```python
+# create figure
+fs = USGSFigure(figure_type="graph", verbose=False)
+
+# ...add some plots
+
+# add a heading
+title = f"Layer {ilay + 1}"
+letter = chr(ord("@") + idx + 2)
+fs.heading(letter=letter, heading=title)
+
+# add an annotation
+fs.add_annotation(
+    ax=ax,
+    text="Well 1, layer 2",
+    bold=False,
+    italic=False,
+    xy=w1loc,
+    xytext=(w1loc[0] - 3200, w1loc[1] + 1500),
+    ha="right",
+    va="center",
+    zorder=100,
+    arrowprops=arrow_props,
+)
+```

docs/md/latex.md

@@ -0,0 +1,3 @@
+# LaTeX utilities
+
+The `modflow_devtools.latex` module provides utility functions for building LaTeX tables from arrays.