Set up initial packaging

.flake8

@@ -0,0 +1,3 @@
+[flake8]
+# For black
+max-line-length = 88

.gitignore

@@ -1,5 +1,14 @@
 # Python runtime files
 __pycache__
+.benchmarks
+.pytest_cache
+
+# Python packaging
+*.egg-info
+dist/
+
+# R runtime files
+.Rhistory
 
 # Sphinx build outputs
 doc/_build

README.rst

@@ -0,0 +1,6 @@
+MESSAGEix-Buildings
+*******************
+
+.. image:: https://readthedocs.com/projects/iiasa-energy-program-message-ix-buildings/badge/?version=latest
+   :target: https://docs.messageix.org/projects/buildings/en/latest/?badge=latest
+   :alt: Documentation status

doc/conf.py

@@ -3,25 +3,31 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Project information -----------------------------------------------------
+# -- Project information ---------------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'MESSAGEix-Buildings'
-copyright = '2023, IIASA ECE Program'
-author = 'IIASA ECE Program'
+project = "MESSAGEix-Buildings"
+copyright = "2023, IIASA ECE Program"
+author = "IIASA ECE Program"
 
-# -- General configuration ---------------------------------------------------
+# -- General configuration -------------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+extensions = [
+    "sphinx.ext.intersphinx",
+]
 
-templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+# -- Options for HTML output -----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
+html_theme = "alabaster"
+html_static_path = ["_static"]
 
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+# -- Options for Sphinx.ext.intersphinx ------------------------------------------------
 
-html_theme = 'alabaster'
-html_static_path = ['_static']
+intersphinx_mapping = {
+    "message_ix_models": ("https://docs.messageix.org/projects/models/en/stable", None),
+}

doc/dev.rst

@@ -0,0 +1,36 @@
+Development
+***********
+
+Build the package
+=================
+
+Ensure the Python package `build <https://pypa-build.readthedocs.io>`__ is installed::
+
+    pip install build
+
+In the project base directory, run::
+
+    python -m build
+
+Build the documentation
+=======================
+
+Change into the :file:`./doc/` directory::
+
+    cd doc
+
+Build (for instance) the HTML documentation::
+
+    make html
+
+The terminal output indicates “The HTML pages are in _build/html”.
+Open the file :file:`index.html` in this directory.
+
+Write and run tests
+===================
+
+The :mod:`message_ix_buildings` package has some tests.
+
+Run these using `pytest <https://docs.pytest.org>`__::
+
+    pytest

doc/index.rst

@@ -6,13 +6,22 @@
 Welcome to MESSAGEix-Buildings's documentation!
 ===============================================
 
+“MESSAGEix-Buildings” refers to a collection of linked models, including:
+
+- ACCESS
+- CHILLED
+- :doc:`sturm`
+
+…and their integration with the :doc:`MESSAGEix-GLOBIOM model family <message_ix_models:index>`.
+
+At present, the package :mod:`message_ix_buildings` contains STURM only.
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-
-   testing
+   :hidden:
 
-Here is some description of MESSAGEix-Buildings.
+   sturm
+   dev
 
 Indices and tables
 ==================

doc/sturm.rst

@@ -0,0 +1,31 @@
+STURM
+*****
+
+STURM is one model in the :doc:`MESSAGEix-Buildings <index>` framework.
+It is primarily written in R.
+
+Usage and development
+=====================
+
+One can use STURM via :mod:`message_ix_buildings` in any of the following ways:
+
+1. Install :mod:`message_ix_buildings`, for example::
+
+     pip install message-ix-buildings
+
+   Locate the installation directory::
+
+     pip show message-ix-buildings
+
+2. Clone the repository from GitHub (https://github.com/iiasa/message-ix-buildings/), for example::
+
+     git clone [email protected]:iiasa/message-ix-buildings.git
+
+   This creates a directory named :file:`message-ix-buildings`.
+
+In either case, all the STURM files are in a further subdirectory named :file:`./message_ix_buildings/sturm/`.
+They are organized into 3 directories:
+
+- :file:`./data/` —input data.
+- :file:`./model/` —R code.
+- :file:`./output/` —example outputs.

pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["build", "setuptools-scm"]
+
+[project]
+dynamic = ["version"]
+name = "message-ix-buildings"
+authors = [
+  {name = "IIASA ECE Program"}
+]
+maintainers = [
+  {name = "Xiaoyang Zhong", email = "[email protected]"},
+  {name = "Alessio Mastrucci", email = "[email protected]"},
+  {name = "Paul Natsuo Kishimoto", email = "[email protected]"},
+  {name = "Fridolin Glatter", email = "[email protected]"},
+]
+readme = "README.rst"
+
+[project.urls]
+homepage = "https://github.com/iiasa/message-ix-buildings"
+repository = "https://github.com/iiasa/message-ix-buildings"
+documentation = "https://docs.messageix.org/buildings/"
+
+[project.optional-dependencies]
+docs = [
+  "Sphinx",
+]
+tests = [
+  "pytest",
+]
+
+[tool.setuptools.packages]
+find = {}
+
+[tool.setuptools_scm]