Adding documentation

README.rst

@@ -1,5 +1,6 @@
-Python Vehicle Routing Open-source Optimization Machine
-=======================================================
+=======
+PyVROOM
+=======
 
 |gh_action| |codecov| |pypi|
 
@@ -34,36 +35,32 @@ Basic usage
 .. code:: python
 
   >>> import vroom
-
+  >>>
   >>> problem_instance = vroom.Input()
-
   >>> problem_instance.set_durations_matrix(
   ...     profile="car",
   ...     matrix_input=[[0, 2104, 197, 1299],
   ...                   [2103, 0, 2255, 3152],
   ...                   [197, 2256, 0, 1102],
   ...                   [1299, 3153, 1102, 0]],
   ... )
-
   >>> problem_instance.add_vehicle([vroom.Vehicle(47, start=0, end=0),
   ...                               vroom.Vehicle(48, start=2, end=2)])
-
   >>> problem_instance.add_job([vroom.Job(1414, location=0),
   ...                           vroom.Job(1515, location=1),
   ...                           vroom.Job(1616, location=2),
   ...                           vroom.Job(1717, location=3)])
-
   >>> solution = problem_instance.solve(exploration_level=5, nb_threads=4)
-
+  >>>
   >>> solution.summary.cost
   6411
-
   >>> solution.routes.columns
   Index(['vehicle_id', 'type', 'arrival', 'duration', 'setup', 'service',
          'waiting_time', 'location_index', 'id', 'description'],
         dtype='object')
 
-  >>> solution.routes[["vehicle_id", "type", "arrival", "location_index", "id"]]
+  >>> solution.routes[[
+  ...     "vehicle_id", "type", "arrival", "location_index", "id"]]
      vehicle_id   type  arrival  location_index    id
   0          47  start        0               0  <NA>
   1          47    job     2104               1  1515
@@ -80,13 +77,13 @@ Usage with a routing engine
 .. code:: python
 
   >>> import vroom
-
+  >>>
   >>> problem_instance = vroom.Input(
   ...     servers={"auto": "valhalla1.openstreetmap.de:443"},
   ...     router=vroom._vroom.ROUTER.VALHALLA
   ... )
-
-  >>> problem_instance.add_vehicle(vroom.Vehicle(1, start=(2.44, 48.81), profile="auto"))
+  >>> problem_instance.add_vehicle(
+  ...     vroom.Vehicle(1, start=(2.44, 48.81), profile="auto"))
 
   >>> problem_instance.add_job([
   ...     vroom.Job(1, location=(2.44, 48.81)),
@@ -169,14 +166,3 @@ To install using Conan, do the following:
 
   cd pyvroom/
   conan install --build=openssl --install-folder conan_build .
-
-Documentation
--------------
-
-The code is currently only documented with Pydoc. This means that the best way
-to learn Pyvroom for now is to either look at the source code or use ``dir()``
-and ``help()`` to navigate the interface.
-
-It is also useful to take a look at the
-`VROOM API documentation <https://github.com/VROOM-Project/vroom/blob/master/docs/API.md>`_.
-The interface there is mostly the same.

docs/_config.yml

@@ -0,0 +1,16 @@
+---
+title: Pyvroom
+author: Jonathan Feinberg
+logo: vroom.svg
+repository:
+    url: https://github.com/VROOM-Project/pyvroom
+    path_to_book: docs
+    branch: main
+html:
+    use_repository_button: true
+sphinx:
+    extra_extensions:
+        - sphinx.ext.autosummary
+        - sphinx_copybutton
+    config:
+        autosummary_generate: true

docs/_toc.yml

@@ -0,0 +1,5 @@
+---
+format: jb-book
+root: readme
+chapters:
+    - file: documentation

docs/documentation.rst

@@ -0,0 +1,41 @@
+=============
+Documentation
+=============
+
+Pyvroom tries to align its functionality close to `VROOM
+<https://github.com/VROOM-Project/vroom>`_. Please see `VROOM API documentation
+<https://github.com/VROOM-Project/vroom/blob/master/docs/API.md>`_ for an
+overview of what VROOM is capable of.
+
+For pragmatic reasons tiny differences might exist here and there. For that
+reason, use the following reference documentation.
+
+Reference
+=========
+
+.. currentmodule:: vroom
+
+.. autosummary::
+   :toctree: reference
+
+   Amount
+   Break
+   ForcedService
+   Input
+   Job
+   Location
+   LocationCoordinates
+   LocationIndex
+   Shipment
+   ShipmentStep
+   Solution
+   TimeWindow
+   Vehicle
+   VehicleCosts
+   VehicleStep
+   VehicleStepBreak
+   VehicleStepDelivery
+   VehicleStepEnd
+   VehicleStepPickup
+   VehicleStepSingle
+   VehicleStepStart

docs/readme.rst

@@ -0,0 +1 @@
+../README.rst

docs/requirements.txt

@@ -0,0 +1,2 @@
+jupyter-book
+sphinx-copybutton

src/vroom/__init__.py

@@ -23,7 +23,7 @@
     VehicleStepDelivery,
     VEHICLE_STEP_TYPE,
 )
-
+from .solution.solution import Solution
 
 def main(argv: Optional[Sequence[str]] = None) -> None:
     """Run VROOM command line interface."""