Add documentation (#87)

* Initial start on documentation

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix name of sphinx_rtd_theme in environment

* Ignore conf.py in pre-commit

* Add numpydoc as a requirement for the documentation

* Add ipython to build environment as well

* Better configuration pre-commit checks

* Use basic conf.py file

* Add untracked files

* Add intersphinx and API reference page

* Add some basic documentation

* Specify calendar type in datetime constructor

* Consistent style

* Add release notes page

* Remove indexes and tables section of index.rst

* Add untracked release-notes.rst file

* Minor edits

* Add docstrings for nc-time-axis objects

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add a little more organization to the index page

* Further minor cleanup

* Configure side-bar a little more

* Fix typos

* Typo

* Add bug fix note for setting axes ticks

* Minor edits to release notes

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.flake8

@@ -26,3 +26,4 @@ ignore =
 exclude = 
     .eggs
     build
+    docs/conf.py

.readthedocs.yml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+    image: latest
+
+conda:
+    environment: requirements/docs.yml
+
+sphinx:
+    configuration: docs/conf.py
+    fail_on_warning: false
+
+python:
+    install:
+        - method: setuptools
+          path: .

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,61 @@
+.. _api:
+
+.. currentmodule:: nc_time_axis
+
+API reference
+=============
+
+This page provides a reference for the API of nc-time-axis.
+
+CalendarDateTime
+----------------
+
+For historical reasons, nc-time-axis defines a :py:class:`CalendarDateTime`
+class which encapsulates a :py:class:`cftime.datetime` object and its calendar
+type.  This is no longer needed, and will be removed in nc-time-axis version
+1.5, but we document it here for now.
+
+.. autosummary::
+    :toctree: _api_generated/
+
+    CalendarDateTime
+
+Formatters
+----------
+
+The :py:class:`AutoCFTimeFormatter` is what is used by default when plotting
+:py:class:`cftime.datetime` axis; it will automatically pick a date label format
+depending on the axis range.  If you would like more control over the format of
+the date labels you may use the :py:class:`CFTimeFormatter` class.
+
+.. autosummary::
+    :toctree: _api_generated/
+
+    AutoCFTimeFormatter
+    CFTimeFormatter
+
+Locators
+--------
+
+The :py:class:`NetCDFTimeDateLocator` is what is used by default to set the tick
+locations depending on the range of the axis.  For finer-grained control over
+the tick locations, use matplotlib's :py:meth:`matplotlib.axes.Axes.set_xticks`
+or :py:meth:`matplotlib.axes.Axes.set_yticks` methods to set the tick locations
+explicitly.
+
+.. autosummary::
+    :toctree: _api_generated/
+
+    NetCDFTimeDateLocator
+
+Converters
+----------
+
+Internally, nc-time-axis must convert times to numerical values so that
+matplotlib can plot them on axes.  The :py:class:`NetCDFTimeConverter` is used
+for this purpose.
+
+.. autosummary::
+    :toctree: _api_generated/
+
+    NetCDFTimeConverter

docs/conf.py

@@ -0,0 +1,79 @@
+# 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 sys
+# sys.path.insert(0, os.path.abspath('.'))
+import datetime
+
+# -- Project information -----------------------------------------------------
+
+project = 'nc-time-axis'
+year = datetime.datetime.today().year
+copyright = f'2016-{year}, nc-time-axis developers'
+author = 'nc-time-axis developers'
+
+
+# -- 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.autosummary',
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    'numpydoc',
+    "IPython.sphinxext.ipython_directive",
+    "IPython.sphinxext.ipython_console_highlighting",
+]
+
+# 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', '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 = '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,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+intersphinx_mapping = {
+    "cftime": ("https://unidata.github.io/cftime", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "python": ("https://docs.python.org/3/", None),
+}
+
+extlinks = {
+    "discussion": ("https://github.com/SciTools/nc-time-axis/discussions/%s", "GH"),
+    "issue": ("https://github.com/SciTools/nc-time-axis/issues/%s", "GH"),
+    "pull": ("https://github.com/SciTools/nc-time-axis/pull/%s", "PR"),
+}
+
+autosummary_generate = True
+
+html_theme_options = {
+    'navigation_depth': 2,
+}

docs/examples.rst

@@ -0,0 +1,56 @@
+.. _examples:
+
+.. currentmodule:: nc_time_axis
+
+Examples
+========
+
+Basic usage
+-----------
+
+nc-time-axis works by adding converters to matplotlib's flexible `units registry
+<https://matplotlib.org/stable/api/units_api.html>`_.  To register its
+converters, simply import nc-time-axis.  Then you will be able to make plots
+with :py:class:`cftime.datetime` axes.
+
+.. ipython:: python
+    :okwarning:
+
+    import cftime
+    import matplotlib.pyplot as plt
+    import nc_time_axis
+    import numpy as np
+
+    fig, ax = plt.subplots(1, 1)
+    x = np.linspace(0, 6 * np.pi)
+    y = 0.5 * x + np.sin(x)
+    times = cftime.num2date(x, units="days since 2000-01-01", calendar="noleap")
+    ax.plot(times, y);
+
+    @savefig basic.png
+    fig.show()
+
+Setting the axes ticks and tick format
+--------------------------------------
+
+In the first example, the ticks and tick label formats were chosen automatically
+using heuristics in nc-time-axis.  If you would like to explicitly set the tick
+positions and label format you may do so using
+:py:meth:`matplotlib.axes.Axes.set_xticks` and :py:class:`CFTimeFormatter`.  The
+:py:class:`CFTimeFormatter` takes in a date format string (see `the Python
+documentation
+<https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes>`_
+for acceptable format codes) and the calendar type of the axis (see
+the :py:class:`cftime.datetime` documentation for valid calendar strings).
+
+.. ipython:: python
+    :okwarning:
+
+    fig, ax = plt.subplots(1, 1)
+    ax.plot(times, y);
+    ax.set_xticks([cftime.datetime(2000, 1, day, calendar="noleap") for day in range(2, 19, 4)]);
+    formatter = nc_time_axis.CFTimeFormatter("%m-%d %H:%M", "noleap")
+    ax.xaxis.set_major_formatter(formatter)
+
+    @savefig set_ticks.png
+    fig.show()

docs/index.rst

@@ -0,0 +1,24 @@
+.. nc-time-axis documentation master file, created by
+   sphinx-quickstart on Tue Aug 17 14:53:26 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+nc-time-axis
+============
+
+**nc-time-axis** is a package that enables making plots in matplotlib with axes made
+up of :py:class:`cftime.datetime` dates with any calendar type.  
+
+.. toctree::
+   :caption: Getting started
+   :maxdepth: 1
+
+   installation
+   examples
+
+.. toctree::
+   :caption: Reference
+   :maxdepth: 1
+
+   release-notes
+   api

docs/installation.rst

@@ -0,0 +1,30 @@
+.. _installation:
+
+Installation
+============
+
+Minimum requirements
+--------------------
+
+* `cftime <https://unidata.github.io/cftime>`_ >= 1.5
+* `matplotlib <https://matplotlib.org/stable>`_
+* `numpy <https://numpy.org/doc/stable>`_
+* `python <https://docs.python.org/3>`_ >= 3.7
+
+Test requirements
+-----------------
+
+For testing, nc-time-axis also depends on pytest:
+
+* `pytest <https://docs.pytest.org/en/6.2.x>`_ >= 6.0
+
+Installation methods
+--------------------
+
+nc-time-axis can be installed through `conda <https://docs.conda.io/projects/conda/en/latest/index.html>`_::
+
+    conda install -c conda-forge nc-time-axis
+
+or through `pip <https://pip.pypa.io/en/stable>`_::
+
+    pip install nc-time-axis