Add technical documentation for the package

- use sphinx to document the developed package
- create a nox session "docs" that builds the docs
- include a skeleton in the docs/ folder
  + how to install the package
  + how to use nox
  + license

docs/conf.py

@@ -0,0 +1,15 @@
+"""Configure sphinx."""
+
+import urban_meal_delivery as umd
+
+
+project = umd.__pkg_name__
+author = umd.__author__
+copyright = f'2020, {author}'  # pylint:disable=redefined-builtin
+version = release = umd.__version__
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx_autodoc_typehints',
+]

docs/index.rst

@@ -0,0 +1,95 @@
+Urban Meal Delivery
+===================
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   license
+   reference
+
+
+This is the documentation for the `urban-meal-delivery` package
+that contains all the source code
+used in a research project
+residing in this `repository`_.
+
+
+Prerequisites
+-------------
+
+Only `git`_, `Python`_ 3.8 and `poetry`_ must be available.
+All other software is automatically installed (cf., next section).
+
+
+Installation
+------------
+
+The `urban-meal-delivery` package is installed
+only after cloning the `repository`_.
+It is *not* available on `PyPI`_ via `pip`_.
+
+.. code-block:: console
+
+   $ git clone https://github.com/webartifex/urban-meal-delivery.git
+
+Use `poetry`_ to install the package
+with its dependencies into a `virtual environment`_,
+which we also refer to as the **local** or the **develop** environment here.
+
+.. code-block:: console
+
+   $ poetry install
+
+
+First Steps
+-----------
+
+Verify that the installation is in a good state by
+running the test suite and the code linters
+via the automated task runner `nox`_.
+
+``poetry run`` executes whatever comes after it in the develop environment.
+If you have a project-independent `nox`_ installation available,
+you may drop the ``poetry run`` prefix.
+Otherwise, `nox`_ was installed as a develop dependency in the `virtual environment`_
+in the installation step above.
+
+Run the default sessions in `nox`_:
+
+.. code-block:: console
+
+   $ [poetry run] nox
+
+`nox`_ provides many options.
+You can use them to choose among the different tasks you want to achieve.
+
+.. option:: -l, --list
+
+   List all available `nox`_ sessions.
+   This includes sessions that are *not* run by default
+   and that may be used as develop tools
+   to work on the source files.
+
+.. option:: -s [SESSION [SESSION ...]], --session[s] [SESSION [SESSION ...]]
+
+   Run only the specified session[s]
+
+.. option:: -r, --reuse-existing-virtualenvs
+
+   By default,
+   `nox`_ creates a new `virtual environment`_ for every session.
+   To speed things up,
+   one can re-use existing environments with the -r flag.
+   This should only be done when developing
+   and not before committing or on the CI server.
+
+
+.. _git: https://git-scm.com/
+.. _nox: https://nox.thea.codes/en/stable/
+.. _pip: https://pip.pypa.io/en/stable/
+.. _poetry: https://python-poetry.org/docs/
+.. _pypi: https://pypi.org/
+.. _python: https://docs.python.org/3/
+.. _repository: https://github.com/webartifex/urban-meal-delivery
+.. _virtual environment: https://docs.python.org/3/tutorial/venv.html

docs/license.rst

@@ -0,0 +1,4 @@
+License
+=======
+
+.. include:: ../LICENSE.txt

docs/reference.rst

@@ -0,0 +1,6 @@
+Reference
+=========
+
+.. contents::
+    :local:
+    :backlinks: none