Rebuild sphinx docs from scratch following sphinx guide

ks905383 · Feb 15, 2024 · ec66417 · ec66417
1 parent 1ec38ee
commit ec66417
Show file tree

Hide file tree

Showing 20 changed files with 154 additions and 149 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -5,8 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
+SOURCEDIR     = source
+BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
 help:

diff --git a/docs/api_backend.rst b/docs/api_backend.rst
diff --git a/docs/api_user.rst b/docs/api_user.rst
diff --git a/docs/environment.yml b/docs/environment.yml
diff --git a/docs/make.bat b/docs/make.bat
@@ -7,10 +7,8 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set SOURCEDIR=.
-set BUILDDIR=_build
-
-if "%1" == "" goto help
+set SOURCEDIR=source
+set BUILDDIR=build
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -21,10 +19,12 @@ if errorlevel 9009 (
 	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/
+	echo.https://www.sphinx-doc.org/
 	exit /b 1
 )
 
+if "%1" == "" goto help
+
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 

diff --git a/docs/conf.py → docs/source/conf.py b/docs/conf.py → docs/source/conf.py
@@ -1,66 +1,57 @@
 # 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:
+# For the full list of built-in configuration values, 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.
-#
+
 import os
 import sys
-# To allow it to access the xagg folder
-sys.path.insert(0, os.path.abspath('..'))
-#sys.path.insert(0, os.path.abspath('.'))
+#sys.path.insert(0,os.path.abspath('../../xagg/'))
+sys.path.insert(0,os.path.abspath('../..'))
 
 # -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'xagg'
 copyright = '2021-2024, Kevin Schwarzwald'
 author = 'Kevin Schwarzwald'
-
-# The full version, including alpha/beta/rc tags
 release = '0.3.2.0'
 
-
 # -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-import sphinx_rtd_theme
-extensions = [
-	'sphinx_rtd_theme',
-	'sphinx.ext.autodoc',
-	'numpydoc',
-	'nbsphinx',
-]
-#'sphinx.ext.mathjax',
+extensions = ['sphinx.ext.autodoc','sphinx.ext.viewcode','numpydoc','nbsphinx','sphinx_rtd_theme',]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_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 = ['_build', '_html', 'Thumbs.db', '.DS_Store','**.ipynb_checkpoints']
+# (allegedly, adding '_build' (or 'build'?) and "**.ipynb_checkpoints' gets
+# rid of a bunch of "Pygments lexer name 'ipython3' not known" warnings...)
+exclude_patterns = ['build', '_build','html','_html', 'Thumbs.db', '.DS_Store','**.ipynb_checkpoints']
 
 # Don't actually build environment for docs (this was the reason why
 # the API in the docs was coming up empty)
 autodoc_mock_imports = ['pytest','xarray','numpy','scipy','shapely',
-'netcdf4','pandas','geopandas','xesmf','cf_xarray','pytables']
+'netcdf4','pandas','geopandas','cartopy','xesmf','matplotlib','cmocean','cf_xarray','pytables']
 
 
 # -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#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_rtd_theme"
+html_theme = 'sphinx_rtd_theme'
 
 # 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,

diff --git a/docs/index.rst → docs/source/index.rst b/docs/index.rst → docs/source/index.rst
@@ -1,5 +1,5 @@
-.. xagg_new documentation master file, created by
-   sphinx-quickstart on Thu Apr 15 21:20:54 2021.
+.. xagg documentation master file, created by
+   sphinx-quickstart on Thu Feb 15 16:33:56 2024.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
@@ -29,12 +29,11 @@ The simplest code run, involving raster data in an :py:mod:`xarray` :py:class:`D
    notebooks/base_run
    notebooks/full_run.ipynb
    tips
-   api_user
-   api_backend
+   modules
 
 
 Indices and tables
 =================================
-@ -29,4 +106,4 @@ Indices and tables
+* :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
diff --git a/docs/installation.rst → docs/source/installation.rst b/docs/installation.rst → docs/source/installation.rst
@@ -17,10 +17,16 @@ though certain depencies may not be available.
 
 Optional dependencies
 ----------------------------------------
-If using `weights` grids to add another weight layer to the aggregation (e.g., weighting raster data additionally by population density), we recommend installing :py:mod:`xesmf`, which is required for :py:mod:`xagg` to perform regridding if the weight and raster grids are not equal. :py:mod:`xesmf` must be [installed manually](https://xesmf.readthedocs.io/en/stable/installation.html), since its dependencies are not available through ``pip`` (and ``conda`` does not support installing optional dependencies). 
+If using `weights` grids to add another weight layer to the aggregation (e.g., weighting raster data additionally by population density), we recommend installing :py:mod:`xesmf`, which is required for :py:mod:`xagg` to perform regridding if the weight and raster grids are not equal. :py:mod:`xesmf` must be `installed manually <https://xesmf.readthedocs.io/en/stable/installation.html>`_, since its dependencies are not available through ``pip`` (and ``conda`` does not support installing optional dependencies)::
 
+   mamba install -c conda-forge xesmf
 
-If wanting to create diagnostic figures using :py:meth:`weightmap.diag_fig()`, :py:mod:`matplotlib`, :py:mod:`cartopy`, and :py:mod:`cmocean` are additionally required. These can be installed using ``pip`` ::
+
+If wanting to create diagnostic figures using :py:meth:`weightmap.diag_fig()`, :py:mod:`matplotlib`, :py:mod:`cartopy`, and :py:mod:`cmocean` are additionally required. We recommend installing them through ``conda`` or ``mamba``:: 
+
+   mamba install -c conda-forge matplotlib cartopy cmocean
+
+They can be also installed using ``pip`` ::
 
    pip install xagg[plots]
 

diff --git a/docs/intro.rst → docs/source/intro.rst b/docs/intro.rst → docs/source/intro.rst
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
@@ -0,0 +1,7 @@
+xagg
+====
+
+.. toctree::
+   :maxdepth: 4
+
+   xagg
diff --git a/docs/notebooks/base_run.ipynb → docs/source/notebooks/base_run.ipynb b/docs/notebooks/base_run.ipynb → docs/source/notebooks/base_run.ipynb
@@ -29,6 +29,7 @@
    "source": [
     "## Import\n",
     "The sample data in this example are:\n",
+    "\n",
     "- gridded: month-of-year average temperature projections for the end-of-century from a climate model (CCSM4)\n",
     "- shapefiles: US counties"
    ]

diff --git a/docs/notebooks/full_run.ipynb → docs/source/notebooks/full_run.ipynb b/docs/notebooks/full_run.ipynb → docs/source/notebooks/full_run.ipynb
@@ -46,11 +46,11 @@
    "metadata": {},
    "source": [
     "### Extra downloads\n",
-    "Since we will be using an extra `weights` file that must be regridded, we need the optional dependency :py:mod:`xesmf`, which we can install through: \n",
+    "Since we will be using an extra `weights` file that must be regridded, we need the optional dependency `xesmf`, which we can install through: \n",
     "\n",
     "`mamba install -c conda-forge xesmf`\n",
     "\n",
-    "Since we will be using the optional feature :py:meth:`.diag_fig()`, we need the optional dependencies :py:mod:`matplotlib`, :py:mod:`cartopy`, and :py:mod:`cmocean`, which we can install through: \n",
+    "Since we will be using the optional feature `.diag_fig()`, we need the optional dependencies `matplotlib`, `cartopy`, and `cmocean`, which we can install through: \n",
     "\n",
     "`mamba install -c conda-forge matplotlib cartopy cmocean`"
    ]

diff --git a/docs/tips.rst → docs/source/tips.rst b/docs/tips.rst → docs/source/tips.rst
@@ -46,7 +46,7 @@ At the expense of increased memory usage, processing may be sped up using an alt
 
 Create diagnostic figure to inspect raster/polygon overlaps 
 ------------------------------------------------------------
-Once you have created a :py:class:`weightmap`, the following code will create a diagnostic figure, showing a particular polygon (or groups of polygons) + the grid cells that overlap it, colored by the relative overlap of each grid cell with the polygon ::
+Once you have created a :py:class:`weightmap`, the following code will create a diagnostic figure, showing a particular polygon (or groups of polygons) + the grid cells that overlap it, colored by the relative overlap of each grid cell with the polygon (NB: this currently only works if :py:meth:`xa.pixel_overlaps` is run with `subset_to_bbox=False`, or using `subset_find` as detailed in `Detailed Code Run <./full_run.ipynb>`_)::
 
    # Querying polygon by column of the polygon `gdf`
    weightmap.diag_fig({'name':'Alaska'},ds)

diff --git a/docs/source/xagg.rst b/docs/source/xagg.rst
@@ -0,0 +1,61 @@
+xagg package
+============
+
+Submodules
+----------
+
+xagg.auxfuncs module
+--------------------
+
+.. automodule:: xagg.auxfuncs
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+xagg.classes module
+-------------------
+
+.. automodule:: xagg.classes
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+xagg.core module
+----------------
+
+.. automodule:: xagg.core
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+xagg.diag module
+----------------
+
+.. automodule:: xagg.diag
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+xagg.export module
+------------------
+
+.. automodule:: xagg.export
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+xagg.wrappers module
+--------------------
+
+.. automodule:: xagg.wrappers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: xagg
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/requirements.txt b/requirements.txt
diff --git a/xagg/auxfuncs.py b/xagg/auxfuncs.py
@@ -10,7 +10,7 @@ def normalize(a,drop_na = False):
     """ Normalizes the vector `a`
 
     The vector `a` is divided by its sum. If all non-`np.nan` elements of `a` are 0, 
-    then all `np.nan`s are returned.  
+    then a vector with only `np.nan` elements is returned.  
 
     Parameters
     ---------------