Setting up the docs with ReadTheDocs

.gitignore

@@ -12,3 +12,8 @@ ioos_pkg_skeleton/_version.py
 coverage.xml
 gcm_filters/_version.py
 *__pycache__
+
+
+# docs
+docs/_build
+make.bat

README.md

@@ -2,6 +2,7 @@
 
 [![pre-commit](https://github.com/ocean-eddy-cpt/gcm-filters/workflows/pre-commit/badge.svg)](https://github.com/ocean-eddy-cpt/gcm-filters/actions?query=workflow%3Apre-commit)
 [![Tests](https://github.com/ocean-eddy-cpt/gcm-filters/workflows/Tests/badge.svg)](https://github.com/ocean-eddy-cpt/gcm-filters/actions?query=workflow%3ATests)
+[![Documentation Status](https://readthedocs.org/projects/gcm-filters/badge/?version=latest)](https://gcm-filters.readthedocs.io/en/latest/?badge=latest)
 
 Diffusion-based smoothers for coarse-graining GCM data.
 

docs/Makefile

@@ -1,12 +1,12 @@
 # Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = python -msphinx
-SPHINXPROJ    = ioos_pkg_skeleton
-SOURCEDIR     = source
-BUILDDIR      = build
+# 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:

docs/source/ioos_pkg_skeleton.rst → docs/api.rst

@@ -1,7 +1,10 @@
-:mod:`ioos_pkg_skeleton API`
+:mod:`API`
 ----------------------------
 
-.. automodule:: ioos_pkg_skeleton.ioos_pkg_skeleton
+Kernels
+=======
+
+.. automodule:: gcm_filters.kernels
    :members:
    :undoc-members:
    :show-inheritance:

docs/conf.py

@@ -0,0 +1,88 @@
+# 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 os
+import pathlib
+import sys
+
+
+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 gcm_filters  # isort:skip
+
+# -- Project information -----------------------------------------------------
+
+project = "gcm-filters"
+copyright = "2021, gcm-filters developers"
+author = "gcm-filters developers"
+
+# 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 = gcm_filters.__version__.split("+")[0]
+# The full version, including alpha/beta/rc tags.
+release = gcm_filters.__version__
+
+
+# -- 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"]
+
+
+# -- nbsphinx specific options ----------------------------------------------
+# this allows notebooks to be run even if they produce errors.
+nbsphinx_allow_errors = True

docs/environment.yml

@@ -0,0 +1,21 @@
+name: gcm-filters_docs
+dependencies:
+  - python=3.8
+  - numpy
+  - xarray
+  - numpydoc
+  - sphinx
+  - sphinx_rtd_theme
+  - ipython
+  - nbconvert
+  - nbformat
+  - ipykernel # not strictly necessary but this is nice to run notebooks in this env to test
+  - pandoc
+  - pip
+  - pip:
+    - docrep<=0.2.7
+    - nbsphinx
+    - jupyter_client
+    - sphinx_pangeo_theme
+    - sphinx-copybutton
+    - sphinxcontrib-srclinks

docs/index.rst

@@ -0,0 +1,32 @@
+.. gcm-filters documentation master file, created by
+   sphinx-quickstart on Tue Jan 12 09:24:23 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to gcm-filters's documentation!
+=======================================
+
+This is an awesome description of gcm-filters, written in `reStructuredText`_.
+
+You can contribute new sections by either adding a new file (see ``new_section.rst``) or just putting a jupyter notebook
+in the ``docs`` folder (see ``new_section_notebook.ipynb``).
+
+In either case, make sure to add an entry in the ``.. toctree::``. Check out ``index.rst`` how it was done for the above examples.
+
+.. toctree::
+   :maxdepth: 2
+
+   new_section
+   new_section_notebook
+   api
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

docs/new_section.rst

@@ -0,0 +1,2 @@
+Some new exciting Section
+=========================

docs/new_section_notebook.ipynb

@@ -0,0 +1,71 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Another section, but this is actually a Notebook 🤗\n",
+    "\n",
+    "This makes it super easy to wrap complex examples into the documentation. \n",
+    "\n",
+    "It supports\n",
+    "\n",
+    "- Markdown cells\n",
+    "\n",
+    "- Code\n",
+    "\n",
+    "    Both `inline` and separate cells"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Some pseudo code\n",
+    "\n",
+    "from cool_module import cool_function\n",
+    "\n",
+    "cool_function(a, b, b)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And all the other fun stuff, like GIFs (absolutely essential to any of my workflows)\n",
+    "\n",
+    "![](https://media.giphy.com/media/q1MeAPDDMb43K/giphy.gif)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}