Skeleton readthedocs

Inspired by xDEM, building a skeleton readthedocs directory structure.
Compiles but has no content yet.

.readthedocs.yaml

@@ -0,0 +1,43 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  fail_on_warning: false
+
+
+# Build the doc in offline formats
+formats:
+  - pdf
+  - htmlzip
+
+conda:
+  environment: environment.yml
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#   - pdf
+#   - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#   install:
+#     - requirements: docs/requirements.txt

doc/Makefile

@@ -0,0 +1,26 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	echo "Removing build files..."
+	if [[ -d "$(BUILDDIR)" ]]; then rm -r "$(BUILDDIR)"; fi
+	if [[ -d "$(SOURCEDIR)/auto_examples" ]]; then rm -r "$(SOURCEDIR)/auto_examples"; fi
+	if [[ -d "$(SOURCEDIR)/gen_modules" ]]; then rm -r "$(SOURCEDIR)/gen_modules"; fi
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

doc/source/conf.py

@@ -0,0 +1,188 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# The content of this file was inspired by xDEM (https://github.com/GlacioHack/xdem)
+#
+"""
+Read the docs config.
+"""
+
+import os
+import sys
+
+
+# -- Project information -----------------------------------------------------
+
+project = "glacier-flow-tools"
+author = "Andy Aschwanden, Constantine Khrulev and others"
+
+# The full version, including alpha/beta/rc tags
+release = "??"
+
+os.environ["PYTHON"] = sys.executable
+
+
+# -- General configuration ---------------------------------------------------
+
+master_doc = "index"
+
+# 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.ext.autodoc",  # Create the API documentation automatically
+    "sphinx.ext.viewcode",  # Create the "[source]" button in the API to show the source code.
+    "matplotlib.sphinxext.plot_directive",  # Render matplotlib figures from code.
+    "sphinx.ext.autosummary",  # Create API doc summary texts from the docstrings.
+    "sphinx.ext.inheritance_diagram",  # For class inheritance diagrams (see coregistration.rst).
+    "sphinx.ext.graphviz",  # To render graphviz diagrams.
+    "sphinx_design",  # To render nice blocks
+    "sphinx_autodoc_typehints",  # Include type hints in the API documentation.
+    "sphinxcontrib.programoutput",
+    "sphinx_gallery.gen_gallery",  # Examples gallery
+    "sphinx.ext.intersphinx",
+    # "myst_parser",  !! Not needed with myst_nb !! # Form of Markdown that works with sphinx, used a lot by the Sphinx Book Theme
+    "myst_nb",  # MySt for rendering Jupyter notebook in documentation
+]
+
+# For sphinx design to work properly
+myst_enable_extensions = ["colon_fence", "dollarmath"]
+
+# For myst-nb to find the Jupyter kernel (=environment) to run from
+nb_kernel_rgx_aliases = {".*xdem.*": "python3"}
+nb_execution_raise_on_error = True
+
+# autosummary_generate = True
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/", None),
+    "rasterio": ("https://rasterio.readthedocs.io/en/latest", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
+    "pyproj": ("https://pyproj4.github.io/pyproj/stable", None),
+    "geopandas": ("https://geopandas.org/en/stable", None),
+    "xarray": ("https://docs.xarray.dev/en/stable/", None),
+    "rioxarray": ("https://corteva.github.io/rioxarray/stable/", None),
+}
+
+sphinx_gallery_conf = {
+    "examples_dirs": [
+        os.path.join(os.path.dirname(__file__), "../", "../", "examples/basic"),
+        os.path.join(os.path.dirname(__file__), "../", "../", "examples/advanced"),
+    ],  # path to your example scripts
+    "gallery_dirs": ["basic_examples", "advanced_examples"],  # path to where to save gallery generated output
+    "inspect_global_variables": True,  # Make links to the class/function definitions.
+    "reference_url": {
+        # The module you locally document uses None
+        "glacier_flow_tools": None,
+    },
+    # directory where function/class granular galleries are stored
+    "backreferences_dir": "gen_modules/backreferences",
+    "doc_module": ("glacier_flow_tools",),  # which function/class levels are used to create galleries
+    # 'subsection_order': ExplicitOrder([os.path.join(os.path.dirname(__file__), "../", "../", "examples", "basic"),
+    #                                    os.path.join(os.path.dirname(__file__), "../", "../", "examples", "advanced")])
+    "remove_config_comments": True,
+    # To remove comments such as sphinx-gallery-thumbnail-number (only works in code, not in text)
+}
+
+extlinks = {
+    "issue": ("https://github.com/pism/glacier-flow-tools/issues/%s", "GH"),
+    "pull": ("https://github.com/pism/glacier-flow-tools/pull/%s", "PR"),
+}
+
+# For matplotlib figures generate with sphinx plot: (suffix, dpi)
+plot_formats = [(".png", 400)]
+
+# To avoid long path names in inheritance diagrams
+inheritance_alias = {
+    "geoutils.georaster.raster.Raster": "geoutils.Raster",
+    "geoutils.georaster.raster.Mask": "geoutils.Mask",
+    "geoutils.georaster.satimg.SatelliteImage": "geoutils.SatelliteImage",
+    "geoutils.geovector.Vector": "geoutils.Vector",
+    "xdem.dem.DEM": "xdem.DEM",
+    "xdem.coreg.base.Coreg": "xdem.Coreg",
+    "xdem.coreg.affine.AffineCoreg": "xdem.AffineCoreg",
+    "xdem.coreg.biascorr.BiasCorr": "xdem.BiasCorr",
+}
+
+# To have an edge color that works in both dark and light mode
+inheritance_edge_attrs = {"color": "dodgerblue1"}
+
+# To avoid fuzzy PNGs
+graphviz_output_format = "svg"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = [os.path.join(os.path.dirname(__file__), "_templates")]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_templates"]
+
+
+# To ignore warnings due to having myst-nb reading the .ipynb created by sphinx-gallery
+# Should eventually be fixed, see: https://github.com/executablebooks/MyST-NB/issues/363
+def setup(app):
+    """
+    Configure the given application by removing the association with .ipynb files.
+
+    Parameters
+    ----------
+    app : object
+        The application to be configured. It should have a `registry` attribute with a `source_suffix` dictionary.
+    """
+    # Ignore .ipynb files
+    app.registry.source_suffix.pop(".ipynb", None)
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_book_theme"
+html_favicon = "_static/xdem_logo_only.svg"
+html_logo = "_static/xdem_logo.svg"
+html_title = "glacier-flow-tools"
+
+html_theme_options = {
+    "path_to_docs": "doc/source",
+    "use_sidenotes": True,
+    "repository_url": "https://github.com/pism/glacier-flow-tools",
+    "repository_branch": "main",
+    "use_repository_button": True,
+    "use_edit_page_button": True,
+    "use_source_button": True,
+    "use_issues_button": True,
+    "use_download_button": True,
+    "launch_buttons": {
+        "binderhub_url": "https://mybinder.org/",
+        "notebook_interface": "jupyterlab",
+        # For launching Binder in Jupyterlab to open MD files as notebook (downloads them otherwise)
+    },
+    "show_toc_level": 2,  # To show more levels on the right sidebar TOC
+    "logo": {
+        "image_dark": "_static/xdem_logo_dark.svg",
+    },
+}
+
+# For dark mode
+html_context = {
+    # ...
+    "default_mode": "auto"
+}
+
+
+# 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 = ["imgs", "_static"]  # Commented out as we have no custom static data

doc/source/index.md

@@ -0,0 +1,30 @@
+---
+title: glacier-flow-tools
+---
+
+::::{grid}
+:reverse:
+:gutter: 2 1 1 1
+:margin: 4 4 1 1
+
+:::{grid-item}
+:columns: 4
+
+```{image} ./_static/xdem_logo_only.svg
+    :width: 300px
+    :class: only-light
+```
+
+```{image} ./_static/xdem_logo_only_dark.svg
+    :width: 300px
+    :class: only-dark
+```
+:::
+
+:::{grid-item}
+:columns: 8
+:class: sd-fs-3
+:child-align: center
+
+glacier-flow-tools
+::::

environment.yml

@@ -6,10 +6,26 @@ dependencies:
   - mpich-mpicxx
   - setuptools
   - pre-commit
-  - pytest
   - gsl
+
+  # Testing
+  - pytest
   - mypy
   - pylint
+
+  # Doc dependencies
+  - sphinx
+  - pydata-sphinx-theme
+  - sphinx-book-theme>=1.0
+  - sphinxcontrib-programoutput
+  - sphinx-design
+  - sphinx-autodoc-typehints
+  - sphinx-gallery
+  - autovizwidget
+  - graphviz
+  - myst-nb
+  - numpydoc
+
   - pip
   - pip:
       - -r requirements.txt

examples/advanced/README.rst

@@ -0,0 +1,6 @@
+.. _examples-advanced:
+
+Advanced
+========
+
+Some **advanced** examples

examples/basic/README.rst

@@ -0,0 +1,6 @@
+.. _examples-basic:
+
+Basic
+=====
+
+Some **basic** examples