Add Documentation (#86)

* Renewed attempt on docs

* pre-commit refactor

* Trigger new build

* Update dependencies

* Forgot the rtd yml

* Buils env from conda-forge

.gitignore

@@ -53,6 +53,7 @@ coverage.xml
 # Sphinx documentation
 docs/_build/
 doc/_build/
+make.bat
 
 # PyBuilder
 target/

docs/Makefile

@@ -0,0 +1,20 @@
+# 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 = .
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.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)

docs/api.rst

@@ -0,0 +1,14 @@
+:mod:`API`
+-----------------
+
+ .. automodule:: xarrayutils.utils
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+
+ .. automodule:: xarrayutils.plotting
+ :members:
+ :undoc-members:
+ :show-inheritance:
+

docs/conf.py

@@ -0,0 +1,90 @@
+# 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.
+#
+import sys
+import pathlib
+import os
+
+print("python exec:", sys.executable)
+print("sys.path:", sys.path)
+root = pathlib.Path(__file__).parent.parent.absolute()
+os.environ["PYTHONPATH"] = str(root)
+sys.path.insert(0, str(root))
+
+import xarrayutils
+
+# -- Versioning --------------------------------------------------------------
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = xarrayutils.__version__.split("+")[0]
+# The full version, including alpha/beta/rc tags.
+release = xarrayutils.__version__
+
+# -- Project information -----------------------------------------------------
+
+project = "xarrayutils"
+copyright = "2021, xarrayutils Maintainers"
+author = "xarrayutils Maintainers"
+
+
+# -- 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.
+extensions = [
+ "sphinx.ext.autodoc",
+ "sphinx.ext.viewcode",
+ "sphinx.ext.napoleon",
+ "nbsphinx",
+ "recommonmark",
+ "sphinx.ext.mathjax",
+ "sphinx.ext.autosummary",
+ "sphinx.ext.extlinks",
+ "sphinx.ext.intersphinx",
+ "numpydoc",
+ "nbsphinx",
+ "IPython.sphinxext.ipython_directive",
+ "IPython.sphinxext.ipython_console_highlighting",
+ "sphinxcontrib.srclinks",
+]
+
+# 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", "**.ipynb_checkpoints", "Thumbs.db", ".DS_Store"]
+
+
+# -- 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 = "pangeo"
+
+# 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"]
+
+# link to github issues
+extlinks = {
+ "issue": ("https://github.com/jbusecke/xarrayutils/issues/%s", "GH#"),
+ "pull": ("https://github.com/jbusecke/xarrayutils/issues/%s", "GH#"),
+}

doc/environment.yml → docs/environment.yml

@@ -1,10 +1,15 @@
 name: xarrayutils-docs
+channels:
+ - conda-forge
+ - defaults
 dependencies:
  - python
- - future
- - pytest
  - scipy
+ - numpy
+ - xarray
  - numpydoc
+ - pandoc
+ - recommonmark
  - sphinx
  - sphinx_rtd_theme
  - ipykernel
@@ -21,8 +26,9 @@ dependencies:
  - intake-esm
  - gcsfs
  #
+ - pip
  - pip:
- - docrep
  - nbsphinx
  - jupyter_client
- - jupyter-sphinx
+ - sphinx_pangeo_theme
+ - sphinxcontrib-srclinks

docs/index.rst

@@ -0,0 +1,26 @@
+.. xarrayutils documentation master file, created by
+ sphinx-quickstart on Wed Jan 13 12:39:16 2021.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to xarrayutils's documentation!
+=======================================
+
+The most bestest introduction ever.
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+ utils
+ plotting
+ api
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/whats-new.rst → docs/whats-new.rst

@@ -10,7 +10,7 @@ v0.2.0 (unreleased)
 Breaking changes
 ~~~~~~~~~~~~~~~~
 - Refactored implementation of :py:meth:`utils.xr_linregress`: Scales better and
-does not require rechunking the data anymore. No more `nanmask` option available
+ does not require rechunking the data anymore. No more `nanmask` option available
  (:pull:`62`)
  By `Julius Busecke <https://github.com/jbusecke>`_
 

readthedocs.yml

@@ -0,0 +1,9 @@
+conda:
+ file: docs/environment.yml
+python:
+ version: 3.8
+ install:
+ - method: setuptools
+ path: package
+sphinx:
+ fail_on_warning: true