Better documentation

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.4.0
+
+- Updated Grid initialization to have better error messages
+- URLs updated to point to the new repository
+- Better documentation
+
 ## 0.3.1
 
 Enabled weights for BiAStarFinder

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to **python-pathfinding-3D**
+# Contributing to **pathfinding3D**
 
 Please inform the maintainer as early as possible about your planned
 feature developments, extensions, or bugfixes that you are working on.
@@ -7,16 +7,16 @@ what you are trying to do.
 
 ## Pull Requests
 
-The preferred way to contribute to *python-pathfinding-3D* is to fork the main repository on Github, then submit a "pull request"
+The preferred way to contribute to *pathfinding3D* is to fork the main repository on Github, then submit a "pull request"
 (PR):
 
-1. Fork the [project repository](https://github.com/harisankar95/python-pathfinding-3D):
+1. Fork the [project repository](https://github.com/harisankar95/pathfinding3D):
    click on the 'Fork' button near the top of the page. This creates a copy of
    the code under your account on the Github server.
 
 2. Clone this copy to your local disk:
 
-        git clone [email protected]:YourLogin/python-pathfinding-3D.git
+        git clone [email protected]:YourLogin/pathfinding3D.git
 
 3. Create a branch to hold your changes:
 
@@ -41,10 +41,6 @@ and click 'Pull request' to send your changes to the maintainers for review.
 
 Summary: maintainer can push minor changes directly, pull request + 1 reviewer for everything else.
 
-* Usually it is not possible to push directly to the `main` branch of *python-pathfinding-3D* for anyone. Only tiny changes, urgent bugfixes, and maintenance commits can be pushed directly to the `main` branch by the maintainer without a review. "Tiny" means backwards compatibility is mandatory and all tests must succeed. No new feature must be added.
+* Usually it is not possible to push directly to the `main` branch of *pathfinding3D* for anyone. Only tiny changes, urgent bugfixes, and maintenance commits can be pushed directly to the `main` branch by the maintainer without a review. "Tiny" means backwards compatibility is mandatory and all tests must succeed. No new feature must be added.
 
 * Developers should submit pull requests. Those will ideally be reviewed by at least one other developer and merged by the maintainer. New features must be documented and tested. Breaking changes must be discussed and announced in advance with deprecation warnings.
-
-## Project Roadmap
-
-Check the [Issue Tracker](https://github.com/harisankar95/python-pathfinding-3D/issues) for roadmap planning.

README.md

@@ -1,9 +1,9 @@
-# python-pathfinding-3D
+# Pathfinding3D
 
-[![MIT License](https://img.shields.io/github/license/harisankar95/python-pathfinding-3d)](LICENSE)
+[![MIT License](https://img.shields.io/github/license/harisankar95/pathfinding3d)](LICENSE)
 [![PyPI](https://img.shields.io/pypi/v/pathfinding3d)](https://pypi.org/project/pathfinding3d/)
-[![Pipeline](https://github.com/harisankar95/python-pathfinding-3D/actions/workflows/test-main.yml/badge.svg?branch=main)](https://github.com/harisankar95/python-pathfinding-3D/actions/workflows/test-main.yml)
-[![codecov](https://codecov.io/gh/harisankar95/python-pathfinding-3D/branch/main/graph/badge.svg?token=ZQZQZQZQZQ)](https://codecov.io/gh/harisankar95/python-pathfinding-3D)
+[![Pipeline](https://github.com/harisankar95/pathfinding3D/actions/workflows/test-main.yml/badge.svg?branch=main)](https://github.com/harisankar95/pathfinding3D/actions/workflows/test-main.yml)
+[![codecov](https://codecov.io/gh/harisankar95/pathfinding3D/branch/main/graph/badge.svg?token=ZQZQZQZQZQ)](https://codecov.io/gh/harisankar95/pathfinding3D)
 [![codestyle](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 Pathfinding algorithms for python3 froked from [python-pathfinding](https://github.com/brean/python-pathfinding) by [@brean](https://github.com/brean).
@@ -18,21 +18,21 @@ Currently there are 7 path-finders bundled in this library, namely:
 - Iterative Deeping A\* (IDA*)
 - Minimum Spanning Tree (MSP)
 
-Dijkstra and A* take the weight of the fields on the map into account.
+Dijkstra, A\* and Bi-directional A\* take the weight of the fields on the map into account.
 
 ## Installation
 
-This library is provided by pypi, so you can just install the current stable version using pip:
+The package is available on pypi, so you can install it with pip:
 
-```python
+```bash
 pip install pathfinding3d
 ```
 
-see [pathfinding on pypi](https://pypi.org/project/pathfinding3d/)
+see [pathfinding3d on pypi](https://pypi.org/project/pathfinding3d/)
 
 ## Usage examples
 
-For usage examples with detailed descriptions take a look at the [examples](examples/) folder, also take a look at the [test/](test/) folder for more examples, e.g. how to use pandas
+For usage examples with detailed descriptions take a look at the [examples](examples/) folder, also take a look at the [test/](test/) folder for more examples.
 
 ## Rerun the algorithm
 
@@ -70,12 +70,12 @@ You can run the tests locally using pytest. Take a look at the `test`-folder
 
 ## Contributing
 
-Please use the [issue tracker](https://github.com/harisankar95/python-pathfinding-3D/issues) to submit bug reports and feature requests. Please use merge requests as described [here](/CONTRIBUTING.md) to add/adapt functionality.
+Please use the [issue tracker](https://github.com/harisankar95/pathfinding3D/issues) to submit bug reports and feature requests. Please use merge requests as described [here](/CONTRIBUTING.md) to add/adapt functionality.
 
 ## License
 
 python-pathfinding is distributed under the [MIT license](https://opensource.org/licenses/MIT).
 
 ## Authors / Contributers
 
-Authors and contributers are [listed on github](https://github.com/harisankar95/python-pathfinding-3D/graphs/contributors).
+Authors and contributers are [listed on github](https://github.com/harisankar95/pathfinding3D/graphs/contributors).

docs/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Version History
+
+## 0.4.0
+
+- Updated Grid initialization to have better error messages
+- URLs updated to point to the new repository
+- Better documentation
+
+## 0.3.1
+
+Enabled weights for BiAStarFinder
+
+## 0.3
+
+Adds:
+
+- Type hints
+- Sphinx minimal autogenerated documentation
+- codecov badge and workflow
+
+## 0.2
+
+Fixes:
+
+- Version number in setup.py
+- Workflows
+
+Adds:
+
+- Minimum python version to setup.py
+
+## 0.1
+
+Initial release based on [python-pathfinding](https://github.com/brean/python-pathfinding/commit/5ba36fc50602b5b90c365c64b7fb2eee120336b9)

docs/INSTALL.md

@@ -0,0 +1,17 @@
+# Installation
+
+## PyPI
+
+The package is available on pypi, so you can install it with pip:
+
+```bash
+pip install pathfinding3d
+```
+
+## For development purpose use editable mode
+
+```bash
+git clone https://github.com/harisankar95/pathfinding3D
+cd pathfinding3D
+pip install -e .[dev]
+```

docs/INTRO.md

@@ -0,0 +1,17 @@
+# Pathfinding3D
+
+## Introduction
+
+Pathfinding algorithms for python3 froked from [python-pathfinding](https://github.com/brean/python-pathfinding) by [@brean](https://github.com/brean).
+
+Currently there are 7 path-finders bundled in this library, namely:
+
+- A*
+- Dijkstra
+- Best-First
+- Bi-directional A*
+- Breadth First Search (BFS)
+- Iterative Deeping A\* (IDA*)
+- Minimum Spanning Tree (MSP)
+
+Dijkstra, A\* and Bi-directional A\* take the weight of the fields on the map into account.

docs/USAGE.md

@@ -0,0 +1,91 @@
+# Examples
+
+For usage examples with detailed descriptions take a look at the [examples](https://github.com/harisankar95/pathfinding3D/tree/main/examples/) folder, also take a look at the [test/](https://github.com/harisankar95/pathfinding3D/tree/main/test/) folder for more examples.
+
+## Basic usage
+
+A simple usage example to find a path using A*.
+
+1. import the required libraries:
+
+    ```python
+    import numpy as np
+
+    from pathfinding3d.core.diagonal_movement import DiagonalMovement
+    from pathfinding3d.core.grid import Grid
+    from pathfinding3d.core.node import GridNode
+    from pathfinding3d.finder.a_star import AStarFinder
+    ```
+
+1. Create a map using a 2D-list. Any value smaller or equal to 0 describes an obstacle. Any number bigger than 0 describes the weight of a field that can be walked on. The bigger the number the higher the cost to walk that field. We ignore the weight for now, all fields have the same cost of 1. Feel free to create a more complex map or use some sensor data as input for it.
+
+    ```python
+    # is of style 'x, y, z'
+    matrix = np.ones((3, 3, 3))
+    matrix[1, 1, 1] = 0
+    ```
+
+  Note: you can use negative values to describe different types of obstacles. It does not make a difference for the path finding algorithm but it might be useful for your later map evaluation.
+
+1. we create a new grid from this map representation. This will create Node instances for every element of our map. It will also set the size of the map. We assume that your map is a square, so the size width is defined by the length of the outer list, the height by the length of the inner lists, and the depth by the length of the innermost lists.
+
+    ```python
+    grid = Grid(matrix=matrix)
+    ```
+
+1. we get the start and end node from the grid. We assume that the start is at the top left corner and the end at the bottom right corner. You can access the nodes by their coordinates. The first parameter is the x coordinate, the second the y coordinate and the third the z coordinate. The coordinates start at 0. So the top left corner is (0, 0, 0) and the bottom right corner is (2, 2, 2).
+
+    ```python
+    start = grid.node(0, 0, 0)
+    end = grid.node(2, 2, 2)
+    ```
+
+1. create a new instance of our finder and let it do its work. We allow diagonal movement. The `find_path` function does not only return you the path from the start to the end point it also returns the number of times the algorithm needed to be called until a way was found.
+
+    ```python
+    finder = AStarFinder(diagonal_movement=DiagonalMovement.always)
+    path, runs = finder.find_path(start, end, grid)
+    ```
+
+1. thats it. We found a way. Now we can print the result (or do something else with it). Note that the start and end points are part of the path.
+
+    ```python
+    print('operations:', runs, 'path length:', len(path))
+    print('path:', path)
+    ```
+
+Here is the whole example if you just want to copy-and-paste the code and play with it:
+
+```python
+  import numpy as np
+
+  from pathfinding3d.core.diagonal_movement import DiagonalMovement
+  from pathfinding3d.core.grid import Grid
+  from pathfinding3d.core.node import GridNode
+  from pathfinding3d.finder.a_star import AStarFinder
+
+
+  matrix = np.ones((3, 3, 3))
+  matrix[1, 1, 1] = 0
+  grid = Grid(matrix=matrix)
+
+  start = grid.node(0, 0, 0)
+  end = grid.node(2, 2, 2)
+
+  finder = AStarFinder(diagonal_movement=DiagonalMovement.always)
+  path_, runs = finder.find_path(start, end, grid)
+
+  assert isinstance(path_, list)
+  assert len(path_) > 0
+  assert isinstance(runs, int)
+
+  path = []
+  for node in path_:
+      if isinstance(node, GridNode):
+        path.append([node.x, node.y, node.z])
+      elif isinstance(node, tuple):
+        path.append([node[0], node[1], node[2]])
+
+  print('operations:', runs, 'path length:', len(path))
+  print('path:', path)
+```

docs/_static/custom.css

@@ -0,0 +1,77 @@
+/* Based on Stable Baselines 3 theme
+*  https://github.com/DLR-RM/stable-baselines3/
+* */
+:root {
+    --main-bg-color: #B6C8DB;
+    --link-color: #6DB59F;
+}
+
+/* Header fonts y */
+h1,
+h2,
+.rst-content .toctree-wrapper p.caption,
+h3,
+h4,
+h5,
+h6,
+legend,
+p.caption {
+    font-family: "Lato", "proxima-nova", "Helvetica Neue", Arial, sans-serif;
+}
+
+
+/* Docs background */
+.wy-side-nav-search {
+    background-color: var(--main-bg-color);
+}
+
+/* Mobile version */
+.wy-nav-top {
+    background-color: var(--main-bg-color);
+}
+
+/* Change link colors (except for the menu) */
+a {
+    color: var(--link-color);
+}
+
+a:hover {
+    color: #798EA9;
+}
+
+.wy-menu a {
+    color: #b3b3b3;
+}
+
+.wy-menu a:hover {
+    color: #b3b3b3;
+}
+
+a.icon.icon-home {
+    color: #b3b3b3;
+}
+
+.version {
+    color: var(--link-color) !important;
+}
+
+
+/* Make code blocks have a background */
+.codeblock,
+pre.literal-block,
+.rst-content .literal-block,
+.rst-content pre.literal-block,
+div[class^='highlight'] {
+    background: #FFFFFF;
+    ;
+}
+
+/* Change style of types in the docstrings .rst-content .field-list */
+.field-list .xref.py.docutils,
+.field-list code.docutils,
+.field-list .docutils.literal.notranslate {
+    border: None;
+    padding-left: 0;
+    padding-right: 0;
+    color: #404040;
+}

docs/_templates/versions.html

@@ -0,0 +1,27 @@
+{%- if current_version %}
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+    <span class="rst-current-version" data-toggle="rst-current-version">
+        <span class="fa fa-book"> Other Versions</span>
+        v: {{ current_version.name }}
+        <span class="fa fa-caret-down"></span>
+    </span>
+    <div class="rst-other-versions">
+        {%- if versions.tags %}
+        <dl>
+            <dt>Tags</dt>
+            {%- for item in versions.tags %}
+            <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+            {%- endfor %}
+        </dl>
+        {%- endif %}
+        {%- if versions.branches %}
+        <dl>
+            <dt>Branches</dt>
+            {%- for item in versions.branches %}
+            <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+            {%- endfor %}
+        </dl>
+        {%- endif %}
+    </div>
+</div>
+{%- endif %}