From f5bab39f859459ad46e60a9fea82d9e903526685 Mon Sep 17 00:00:00 2001 From: Jonathan Feinberg Date: Mon, 22 Jul 2024 14:42:42 +0200 Subject: [PATCH 1/2] Adding documenation Using Jupyter-book and autosummary to automatically generate a proper reference manual. --- README.rst | 34 ++--- docs/_config.yml | 16 +++ docs/_toc.yml | 5 + docs/conf.py | 0 docs/documentation.rst | 41 ++++++ docs/readme.rst | 1 + docs/requirements.txt | 2 + docs/vroom.svg | 289 +++++++++++++++++++++++++++++++++++++++++ src/vroom/__init__.py | 2 +- 9 files changed, 365 insertions(+), 25 deletions(-) create mode 100644 docs/_config.yml create mode 100644 docs/_toc.yml create mode 100644 docs/conf.py create mode 100644 docs/documentation.rst create mode 120000 docs/readme.rst create mode 100644 docs/requirements.txt create mode 100644 docs/vroom.svg diff --git a/README.rst b/README.rst index 89fd73c..cbf1607 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,6 @@ -Python Vehicle Routing Open-source Optimization Machine -======================================================= +======= +PyVROOM +======= |gh_action| |codecov| |pypi| @@ -34,9 +35,8 @@ Basic usage .. code:: python >>> import vroom - + >>> >>> problem_instance = vroom.Input() - >>> problem_instance.set_durations_matrix( ... profile="car", ... matrix_input=[[0, 2104, 197, 1299], @@ -44,26 +44,23 @@ Basic usage ... [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 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 `_. -The interface there is mostly the same. diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..969ff8c --- /dev/null +++ b/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 diff --git a/docs/_toc.yml b/docs/_toc.yml new file mode 100644 index 0000000..44d543f --- /dev/null +++ b/docs/_toc.yml @@ -0,0 +1,5 @@ +--- +format: jb-book +root: readme +chapters: + - file: documentation diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..e69de29 diff --git a/docs/documentation.rst b/docs/documentation.rst new file mode 100644 index 0000000..7518492 --- /dev/null +++ b/docs/documentation.rst @@ -0,0 +1,41 @@ +============= +Documentation +============= + +Pyvroom tries to align its functionality close to `VROOM +`_. Please see `VROOM API documentation +`_ for an +overview of what VROOM is capable of. + +For pragnatic reasons tiny differences might exists 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 diff --git a/docs/readme.rst b/docs/readme.rst new file mode 120000 index 0000000..89a0106 --- /dev/null +++ b/docs/readme.rst @@ -0,0 +1 @@ +../README.rst \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..c467224 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +jupyter-book +sphinx-copybutton diff --git a/docs/vroom.svg b/docs/vroom.svg new file mode 100644 index 0000000..66a4556 --- /dev/null +++ b/docs/vroom.svg @@ -0,0 +1,289 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/vroom/__init__.py b/src/vroom/__init__.py index 7293df9..6bcc474 100644 --- a/src/vroom/__init__.py +++ b/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.""" From a2bea20fab00515bde0908236277fc95fefb245c Mon Sep 17 00:00:00 2001 From: Jonathan Feinberg Date: Thu, 1 Aug 2024 11:36:45 +0200 Subject: [PATCH 2/2] Update docs/documentation.rst --- docs/documentation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/documentation.rst b/docs/documentation.rst index 7518492..9079913 100644 --- a/docs/documentation.rst +++ b/docs/documentation.rst @@ -7,7 +7,7 @@ Pyvroom tries to align its functionality close to `VROOM `_ for an overview of what VROOM is capable of. -For pragnatic reasons tiny differences might exists here and there. For that +For pragmatic reasons tiny differences might exist here and there. For that reason, use the following reference documentation. Reference