Add TOUGH3 user guide in documentation

doc/requirements.txt

@@ -5,4 +5,5 @@ sphinx-argparse
 sphinx-gallery
 pydata-sphinx-theme
 sphinxcontrib-bibtex
-pybtex-apa-style
+pybtex-apa-style
+sphinx_subfigure

doc/source/_static/css/custom.css

@@ -0,0 +1,9 @@
+html[data-theme="light"] {
+    --pst-color-link: #0274be;
+    --pst-color-primary: black;
+}
+
+html[data-theme="dark"] {
+    --pst-color-link: #0274be;
+    --pst-color-primary: white;
+}

doc/source/conf.py

@@ -42,8 +42,9 @@
     "sphinx.ext.githubpages",
     "sphinx.ext.napoleon",
     "sphinxarg.ext",
-    # "sphinxcontrib.bibtex",
+    "sphinxcontrib.bibtex",
     "sphinx_gallery.gen_gallery",
+    "sphinx_subfigure",
 ]
 
 # Sphinx Gallery settings
@@ -85,11 +86,14 @@
 # napoleon_use_rtype = True
 
 # Numfig settings
-numfig = False
+numfig = True
 numfig_format = {
     "figure": "Figure %s",
 }
 
+# BibTeX
+bibtex_bibfiles = ["references.bib"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = [
     "_templates",
@@ -120,13 +124,19 @@
 # a list of builtin themes.
 #
 html_theme = "pydata_sphinx_theme"
+html_logo = "_static/logo.png"
 html_theme_path = [
     "_themes",
 ]
+html_context = {
+    "default_mode": "light",
+}
 
 # 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_static_path = ["_static"]
+
+html_css_files = [
+    "css/custom.css",
+]

doc/source/guide/index.rst

@@ -5,4 +5,5 @@ User Guide
    :titlesonly:
    :maxdepth: 2
 
+   installation
    input

doc/source/guide/installation.rst

@@ -0,0 +1,12 @@
+Installation
+============
+
+**toughio** only requires a Python distribution to be installed. If you don't have any yet, we recommend to install the `Anaconda Distribution <https://www.anaconda.com/>`_ with the default options.
+
+To install **toughio** and enable all its features, simply run the command in a terminal (e.g., Windows Terminal, Anaconda Prompt) or within an IPython shell:
+
+.. code-block::
+
+    pip install toughio[full]
+
+An IDE such as Spyder (automatically installed by Anaconda) or `VSCode <https://code.visualstudio.com/>`_ is strongly recommended to use **toughio**.

doc/source/index.rst

@@ -8,3 +8,4 @@
    guide/index
    examples/index
    api/index
+   tough3/index