migrate docs theme to sphinx-immaterial

CHANGELOG.md

@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   can be set to `True` to return a 2-level dictionary, with the element symbol as the key at the top level, and
   the valence (float, or "unk" for unknown) as the key at the second level. This should make it easier for future
   code to calculate the total amount of a given element regardless of its valence. (#284, @vineetbansal)
+- Docs: `sphinx-material` theme migrated to `sphinx-immaterial` (#2xX, @ugognw, @rkingsbury)
 
 ### Fixed
 
@@ -99,7 +100,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support `numpy>2.0`
 - Bump `pint` to `0.24.4` for `numpy` `v2.0` compatibility and to mitigate CI issues (#239, @SuixiongTay, @rkingsbury)
 - CI: add `python` `v3.13` to post-merge unit tests
-- Docs: `tox -e docs` command configured to fail on warning (#255, @ugognw)
+- Docs: `tox -e docs` command configured to fail on warning (#255, ugognw)
 - Docs: ReadTheDocs built with Python 3.11 (#255, ugognw)
 - Use `importlib` to locate test files (#241, @SuixiongTay)
 - Support `numpy>2.0`

docs/conf.py

@@ -47,6 +47,7 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    "sphinx_immaterial",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
@@ -166,24 +167,20 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "sphinx_material"
+html_theme = "sphinx_immaterial"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
     # "sidebar_width": "300px",
     # "page_width": "1200px",
-    "base_url": "https://pyeql.readthedocs.io/en/latest/",
+    "site_url": "https://pyeql.readthedocs.io/en/latest/",
     "repo_url": "https://github.com/KingsburyLab/pyEQL/",
     "repo_name": "pyEQL",
     # 'logo_icon': 'e798',
-    "html_minify": True,
-    "css_minify": True,
-    "nav_title": "pyEQL: a python interface for water chemistry",
-    "color_primary": "blue",
-    "color_accent": "light-blue",
-    "globaltoc_depth": 2,
+    "toc_title": "pyEQL: a python interface for water chemistry",
+    "palette": { "primary": "blue", "accent": "light-blue" },
     "globaltoc_collapse": True,
 }
 html_sidebars = {"**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]}

docs/contributing.md

@@ -128,7 +128,7 @@ Please abide by the following guidelines when contributing code to `pyEQL`:
 
 ## Documentation
 
-Improvements to the documentation are most welcome! Our documentation system uses `sphinx` with the [Materials for Sphinx](https://bashtage.github.io/sphinx-material/) theme. To edit the documentation locally, run `tox -e autodocs` from the repository root directory. This will serve the documents to `http://localhost:8000/` so you can view them in your web browser. When you make changes to the files in the `docs/` directory, the documentation will automatically rebuild and update in your browser (you might have to refresh the page to see changes).
+Improvements to the documentation are most welcome! Our documentation system uses `sphinx` with the [Sphinx-Immaterial](https://jbms.github.io/sphinx-immaterial/) theme. To edit the documentation locally, run `tox -e autodocs` from the repository root directory. This will serve the documents to `http://localhost:8000/` so you can view them in your web browser. When you make changes to the files in the `docs/` directory, the documentation will automatically rebuild and update in your browser (you might have to refresh the page to see changes).
 
 ## Changelog
 

docs/requirements.txt

@@ -1,17 +1,17 @@
 # Requirements file for ReadTheDocs, check .readthedocs.yml.
 # To build the module reference correctly, make sure every external package
 # under `install_requires` in `setup.cfg` is also listed here!
-pint>=0.19
-numpy
-scipy
-pymatgen>=2024.9.10
-iapws
-monty
-maggma
-phreeqpython
+pint>=0.24.4
+numpy>1.26
+scipy>=1.12
+pymatgen>=2025.1.9
+iapws>=1.5.3
+monty>=2024.12.10
+maggma>=0.71.4
+phreeqpython>=1.5.2
 sphinx>=3.2.1
 nbsphinx
 sphinx-rtd-theme
 ipython>=9.3.0
 myst-parser[linkify]
-git+https://github.com/bashtage/sphinx-material.git # Material theme
+sphinx-immaterial # Material theme

src/pyEQL/solution.py

@@ -506,9 +506,6 @@ def dielectric_constant(self) -> Quantity:
         r"""
         Returns the dielectric constant of the solution.
 
-        Args:
-            None
-
         Returns:
             Quantity: the dielectric constant of the solution, dimensionless.
 
@@ -1294,10 +1291,10 @@ def add_solute(self, formula: str, amount: str):
         """Primary method for adding substances to a pyEQL solution.
 
         Args:
-            formula (str): Chemical formula for the solute. Charged species must contain a + or - and
-            (for polyvalent solutes) a number representing the net charge (e.g. 'SO4-2').
-            amount (str): The amount of substance in the specified unit system. The string should contain
-            both a quantity and a pint-compatible representation of a ureg. e.g. '5 mol/kg' or '0.1 g/L'.
+            formula (str): Chemical formula for the solute. Charged species must contain a+ or - and
+               (for polyvalent solutes) a number representing the net charge (e.g. 'SO4-2').
+            amount (str): The amount of substance in the specified unit system. The string should
+               contain both a quantity and a pint-compatible representation of a ureg. e.g. '5 mol/kg' or '0.1 g/L'.
         """
         # if units are given on a per-volume basis,
         # iteratively solve for the amount of solute that will preserve the
@@ -1719,9 +1716,6 @@ def get_activity_coefficient(
         Args:
             solute: The solute for which to retrieve the activity coefficient
             scale:  The activity coefficient concentration scale
-            verbose: If True, pyEQL will print a message indicating the parent salt
-                     that is being used for activity calculations. This option is
-                     useful when modeling multicomponent solutions. False by default.
 
         Returns:
             Quantity: the activity coefficient as a dimensionless pint Quantity
@@ -1766,10 +1760,6 @@ def get_activity(
                 The concentration scale for the returned activity.
                 Valid options are "molal", "molar", and "rational" (i.e., mole fraction).
                 By default, the molal scale activity is returned.
-            verbose:
-                If True, pyEQL will print a message indicating the parent salt
-                that is being used for activity calculations. This option is
-                useful when modeling multicomponent solutions. False by default.
 
         Returns:
             The thermodynamic activity of the solute in question (dimensionless Quantity)