Merge pull request #3 from khaeru/packaging2

Set up basic packaging

.github/workflows/lint.yml

@@ -0,0 +1,71 @@
+name: lint
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+env:
+  # For setuptools-scm. With fetch --tags below, this ensures that
+  # enough history is fetched to contain the latest tag, so that
+  # setuptools-scm can generate the version number. Update:
+  # - See https://github.com/khaeru/genno/releases, at "NN commits to
+  #   master since this release". The value should be at least equal to
+  #   NN + the number of commits on any PR branch.
+  # - Reset to a lower value, e.g. 100, after a new release.
+  depth: 100
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    continue-on-error: true
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: ${{ env.depth }}
+
+    - name: Fetch tags (for setuptools-scm)
+      run: git fetch --tags --depth=${{ env.depth }}
+
+    - uses: actions/setup-python@v2
+      with:
+        # This should match the "Latest version testable on GitHub Actions"
+        # in pytest.yml
+        python-version: "3.8"
+
+    - name: Cache Python packages
+      uses: actions/cache@v2
+      with:
+        path: |
+          ~/.cache/pip
+          ~/Library/Caches/pip
+          ~/appdata/local/pip/cache
+        key: lint-${{ runner.os }}
+
+    - name: Upgrade pip, wheel, setuptools-scm
+      run: python -m pip install --upgrade pip wheel setuptools-scm
+
+    - name: Check "black" code style
+      run: |
+        pip install black
+        black --check .
+
+    - name: Lint with flake8 & isort
+      run: |
+        pip install flake8 isort
+        flake8 --count --max-complexity=26 --show-source --statistics
+        isort --check-only .
+
+    - name: Check typing with mypy
+      run: |
+        pip install mypy pytest xarray
+        mypy .
+
+    - name: Test package build
+      run: |
+        pip install twine wheel
+        python3 setup.py bdist_wheel sdist
+        twine check dist/*

.gitignore

@@ -0,0 +1,17 @@
+# Python and packaging files
+*.egg-info
+__pycache__
+build
+dist
+
+# pytest, pytest-benchmark, pytest-cov
+.benchmarks
+.coverage
+.pytest_cache
+htmlcov
+
+# mypy
+.mypy_cache
+
+# sphinx
+doc/_build

conftest.py

@@ -0,0 +1,4 @@
+# Include ixmp test fixtures, e.g. pre-populated Scenario objects
+# TODO remove this dependency
+# NB genno must follow ixmp, since pytest prefers fixtures etc. from later in the list
+pytest_plugins = ["ixmp.testing", "genno.testing"]

doc/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)

doc/conf.py

@@ -0,0 +1,52 @@
+# 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
+
+
+# -- Project information ---------------------------------------------------------------
+
+project = "genno"
+copyright = "2021, Genno Contributors"
+author = "Genno Contributors"
+
+
+# -- 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.intersphinx",
+    "sphinx.ext.napoleon",
+]
+
+# 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"]
+
+# -- Options for sphinx.ext.intersphinx ------------------------------------------------
+
+intersphinx_mapping = {
+    "dask": ("https://docs.dask.org/en/stable/", None),
+    "pint": ("https://pint.readthedocs.io/en/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+}

doc/index.rst

@@ -1,7 +1,27 @@
-.. currentmodule:: ixmp.reporting
+.. genno documentation master file, created by
+   sphinx-quickstart on Fri Jan  8 16:17:54 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
 
-Reporting
-*********
+Welcome to genno's documentation!
+*********************************
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+Indices and tables
+******************
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+API
+***
+
+.. currentmodule:: genno
 
 Top-level methods and classes:
 
@@ -18,9 +38,9 @@ Others:
    :local:
    :depth: 3
 
-.. automethod:: ixmp.reporting.configure
+.. autofunction:: configure
 
-.. autoclass:: ixmp.reporting.Reporter
+.. autoclass:: genno.Reporter
    :members:
    :exclude-members: graph, add, add_load_file, apply
 
@@ -129,7 +149,7 @@ Others:
 
          rep.apply(my_gen, units='kg')
 
-.. autoclass:: ixmp.reporting.Key
+.. autoclass:: genno.Key
    :members:
 
    Quantities in a :class:`Scenario` can be indexed by one or more dimensions.
@@ -183,7 +203,7 @@ Others:
           >>> foo('a b c')
           foo:a-b-c
 
-.. autodata:: ixmp.reporting.Quantity(data, *args, **kwargs)
+.. autodata:: genno.Quantity(data, *args, **kwargs)
    :annotation:
 
 The :data:`.Quantity` constructor converts its arguments to an internal, :class:`xarray.DataArray`-like data format:
@@ -197,22 +217,22 @@ The :data:`.Quantity` constructor converts its arguments to an internal, :class:
    qty = Quantity(data, name="Quantity name", units="kg")
    rep.add("new_qty", qty)
 
-Common :mod:`ixmp.reporting` usage, e.g. in :mod:`message_ix`, creates large, sparse data frames (billions of possible elements, but <1% populated); :class:`~xarray.DataArray`'s default, 'dense' storage format would be too large for available memory.
+Common :mod:`genno` usage, e.g. in :mod:`message_ix`, creates large, sparse data frames (billions of possible elements, but <1% populated); :class:`~xarray.DataArray`'s default, 'dense' storage format would be too large for available memory.
 
 - Currently, Quantity is :class:`.AttrSeries`, a wrapped :class:`pandas.Series` that behaves like a :class:`~xarray.DataArray`.
-- In the future, :mod:`ixmp.reporting` will use :class:`.SparseDataArray`, and eventually :class:`~xarray.DataArray` backed by sparse data, directly.
+- In the future, :mod:`genno` will use :class:`.SparseDataArray`, and eventually :class:`~xarray.DataArray` backed by sparse data, directly.
 
 The goal is that reporting code, including built-in and user computations, can treat quantity arguments as if they were :class:`~xarray.DataArray`.
 
 
 Computations
 ============
 
-.. automodule:: ixmp.reporting.computations
+.. automodule:: genno.computations
    :members:
 
    Unless otherwise specified, these methods accept and return
-   :class:`Quantity <ixmp.reporting.utils.Quantity>` objects for data
+   :class:`Quantity <genno.utils.Quantity>` objects for data
    arguments/return values.
 
    Calculations:
@@ -242,24 +262,24 @@ Computations
 Internal format for reporting quantities
 ========================================
 
-.. currentmodule:: ixmp.reporting.quantity
+.. currentmodule:: genno.quantity
 
-.. automodule:: ixmp.reporting.quantity
+.. automodule:: genno.quantity
    :members: assert_quantity
 
-.. currentmodule:: ixmp.reporting.attrseries
+.. currentmodule:: genno.attrseries
 
-.. automodule:: ixmp.reporting.attrseries
+.. automodule:: genno.attrseries
    :members:
 
-.. currentmodule:: ixmp.reporting.sparsedataarray
+.. currentmodule:: genno.sparsedataarray
 
-.. automodule:: ixmp.reporting.sparsedataarray
+.. automodule:: genno.sparsedataarray
    :members: SparseDataArray, SparseAccessor
 
 
 Utilities
 =========
 
-.. automodule:: ixmp.reporting.utils
+.. automodule:: genno.utils
    :members: