Merge pull request #14 from khaeru/issue/9

Expand documentation
khaeru · Feb 5, 2021 · 607039d · 607039d
2 parents b8fbde6 + 81b091b
commit 607039d
Show file tree

Hide file tree

Showing 9 changed files with 737 additions and 961 deletions.
diff --git a/.gitignore b/.gitignore
@@ -14,4 +14,5 @@ htmlcov
 .mypy_cache
 
 # sphinx
+doc/.ipynb_checkpoints
 doc/_build
diff --git a/doc/.gitignore b/doc/.gitignore
@@ -0,0 +1,3 @@
+# Files generated by tutorial.rst
+output.csv
+westeros_report.pdf
diff --git a/doc/compat.rst b/doc/compat.rst
@@ -14,6 +14,13 @@ Compatibility with other packages
 .. automodule:: genno.compat.ixmp.computations
    :members:
 
+.. automodule:: genno.compat.ixmp.reporter
+   :members:
+
+.. automodule:: genno.compat.ixmp.util
+   :members:
+
+
 
 :mod:`pyam`
 ===========
@@ -27,3 +34,6 @@ Compatibility with other packages
 
 .. automodule:: genno.compat.pyam.computations
    :members:
+
+.. automodule:: genno.compat.pyam.util
+   :members:
diff --git a/doc/conf.py b/doc/conf.py
@@ -16,6 +16,7 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions coming
 # with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    "IPython.sphinxext.ipython_directive",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.extlinks",

diff --git a/doc/index.rst b/doc/index.rst
@@ -1,15 +1,36 @@
-Welcome to genno's documentation!
-*********************************
+``genno``: efficient, transparent calculation on N-D data
+*********************************************************
+
+**genno** is a Python package for describing and executing complex calculations on labelled, multi-dimensional data.
+It aims to make these calculations efficient, transparent, and easily validated as part of scientific research.
+
+genno is built on high-quality Python data packages including ``dask``, ``xarray``, and ``pint``; and provides (current or planned) compatibility with packages including ``pandas``, ``matplotlib``, ``plotnine``, ``ixmp``, ``sdmx1``, and ``pyam``.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Contents
 
+   usage
    api
    compat
    whatsnew
    releasing
 
+License
+=======
+
+Copyright © 2018–2021 genno developers.
+
+Licensed under the GNU General Public License, version 3.0.
+
+
+Name
+====
+
+A 玄能 (*genno* or *gennoh*) is a type of hammer used in Japanese woodworking.
+The package name is warning, by reference, to the adage “When you hold a hammer, every problem looks like a nail”: you shouldn't hit everything with ``genno``, but it is still a useful and versatile tool.
+
+
 Indices and tables
 ==================