Alexander Hess
882226f0a9
- 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
95 lines
2.5 KiB
ReStructuredText
95 lines
2.5 KiB
ReStructuredText
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
|