Implement JOSS reviewer comments regarding documentation (#253)

* readme changed

* readme changed

* Update README.rst

* readme changed

* readme changed

* readme changed

* readme changed

* readme changed

* readme changed

* readme changed

* readme changed

* readme changed

* readme changed

* readme changed

* made installation prerequisites more visible

* made installation prerequisites more visible

* slightly restructured py dispatcher structure + bugfix

* started dispatcher writing guide

* guide almost done

* glossary

* glossary

* guide almost done

* bumped black, fixed broken error logic

.pre-commit-config.yaml

@@ -9,4 +9,4 @@ repos:
     hooks:
     - id: blacken-docs
       additional_dependencies:
-        - black==24.1.1
+        - black==24.2.0

README.rst

@@ -7,24 +7,78 @@ RidePy is a scientific Python library for simulating modern on-demand transit sy
 
 In short: RidePy simulates a dispatching algorithm serving exogenous transportation requests with a fleet of vehicles. Does not simulate the universe, unlike MATSim. Batteries are included.
 
-Head over to `ridepy.org <https://ridepy.org/>`__ to get started.
+Head over to `ridepy.org <ridepy doc_>`_ to get started.
+
+Quickstart
+----------
+
+For detailed instructions, see the `installation guide <https://ridepy.org/setup.html>`__ in the documentation.
+
+If you're in a hurry, here's the gist:
+
+- RidePy currently works best with Python 3.9
+- If you are on platform other than x86-64 Linux, i.e., one that we don't offer wheels for, you will need to first set up a C++ build environment and the `Boost C++ libraries <https://www.boost.org/>`_. On Debian-like systems, this is easily accomplished with
+
+.. code-block:: bash
+
+   sudo apt-get install build-essential libboost-all-dev
+
+- Install RidePy with
+
+.. code-block:: bash
+
+   pip install ridepy
+
+Contributing
+------------
+
+We are always happy for contributions from the community. If you run into a problem, please `report an issue <https://ridepy.org/issues.html>`_ or `ask for help <https://ridepy.org/support.html>`_.
+
+If you are interested in contributing to our codebase, please read our `contributing guide <https://ridepy.org/contributing.html>`_.
+
+Here is a short overview of the most important points:
+
+Resources
+~~~~~~~~~
+
+- Documentation: `ridepy.org <ridepy doc_>`_
+- Source code: `GitHub <https://github.com/PhysicsOfMobility/ridepy>`_
+- Issue tracker: `GitHub <https://github.com/PhysicsOfMobility/ridepy/issues>`_
+
+Code style
+~~~~~~~~~~
+
+- Python: `black <https://github.com/psf/black>`_
+- C++: `LLVM <https://llvm.org/docs/CodingStandards.html>`_
+
+Development
+~~~~~~~~~~~
+
+- Version control: `Git <https://git-scm.com/>`_
+- Testing: `pytest <https://docs.pytest.org/en/stable/>`_
+- Continuous integration: `GitHub Actions <https://github.com/PhysicsOfMobility/ridepy/actions>`_
+- Versioning: `Semantic Versioning <https://semver.org/>`_
+
+.. http://mozillascience.github.io/working-open-workshop/contributing/
 
 ..
     ---------
     Badges
     ---------
 
 .. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
-    :target: https://github.com/psf/black
+   :target: https://github.com/psf/black
 
 .. |Docs| image:: https://github.com/PhysicsOfMobility/ridepy/actions/workflows/build-doc.yml/badge.svg
-    :target: https://github.com/PhysicsOfMobility/ridepy/actions/workflows/build-doc.yml
+   :target: https://github.com/PhysicsOfMobility/ridepy/actions/workflows/build-doc.yml
 
 .. |Tests| image:: https://github.com/PhysicsOfMobility/ridepy/actions/workflows/python-testing.yml/badge.svg
-    :target: https://github.com/PhysicsOfMobility/ridepy/actions/workflows/python-testing.yml
+   :target: https://github.com/PhysicsOfMobility/ridepy/actions/workflows/python-testing.yml
 
 .. |wheel| image:: https://github.com/PhysicsOfMobility/ridepy/actions/workflows/build-wheel.yml/badge.svg
-    :target: https://github.com/PhysicsOfMobility/ridepy/actions/workflows/build-wheel.yml
+   :target: https://github.com/PhysicsOfMobility/ridepy/actions/workflows/build-wheel.yml
 
 .. |sdist| image:: https://github.com/PhysicsOfMobility/ridepy/actions/workflows/build-sdist.yml/badge.svg
-    :target: https://github.com/PhysicsOfMobility/ridepy/actions/workflows/build-sdist.yml
+   :target: https://github.com/PhysicsOfMobility/ridepy/actions/workflows/build-sdist.yml
+
+.. _ridepy doc: https://ridepy.org