From 81b925a3e5b4f6b5f179816f66687151577ac2ff Mon Sep 17 00:00:00 2001 From: Hari Date: Fri, 29 Dec 2023 12:09:36 +0100 Subject: [PATCH] Better documentation --- CHANGELOG.md | 6 +++ CONTRIBUTING.md | 14 ++---- README.md | 22 ++++----- docs/CHANGELOG.md | 34 +++++++++++++ docs/INSTALL.md | 17 +++++++ docs/INTRO.md | 17 +++++++ docs/USAGE.md | 91 +++++++++++++++++++++++++++++++++++ docs/_static/custom.css | 77 +++++++++++++++++++++++++++++ docs/_templates/versions.html | 27 +++++++++++ docs/conf.py | 79 +++++++++++++++++++----------- docs/index.rst | 6 ++- docs/pathfinding3d.core.rst | 13 ++--- docs/pathfinding3d.finder.rst | 13 ++--- docs/pathfinding3d.rst | 13 ++--- pathfinding3d/version.txt | 2 +- setup.cfg | 2 +- setup.py | 33 ++++++++----- 17 files changed, 379 insertions(+), 87 deletions(-) create mode 100644 docs/CHANGELOG.md create mode 100644 docs/INSTALL.md create mode 100644 docs/INTRO.md create mode 100644 docs/USAGE.md create mode 100644 docs/_static/custom.css create mode 100644 docs/_templates/versions.html diff --git a/CHANGELOG.md b/CHANGELOG.md index 51750d1..094b07b 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d4ebe53..bf37607 100644 --- a/CONTRIBUTING.md +++ b/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 git@github.com:YourLogin/python-pathfinding-3D.git + git clone git@github.com: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. diff --git a/README.md b/README.md index b37b429..a37fcc6 100644 --- a/README.md +++ b/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,7 +70,7 @@ 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 @@ -78,4 +78,4 @@ python-pathfinding is distributed under the [MIT license](https://opensource.org ## 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). diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 0000000..5558c43 --- /dev/null +++ b/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) diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 0000000..75bf9c8 --- /dev/null +++ b/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] +``` diff --git a/docs/INTRO.md b/docs/INTRO.md new file mode 100644 index 0000000..96b95f0 --- /dev/null +++ b/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. diff --git a/docs/USAGE.md b/docs/USAGE.md new file mode 100644 index 0000000..aa1eebd --- /dev/null +++ b/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) +``` diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 0000000..ca6b99e --- /dev/null +++ b/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; +} \ No newline at end of file diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html new file mode 100644 index 0000000..c49f844 --- /dev/null +++ b/docs/_templates/versions.html @@ -0,0 +1,27 @@ +{%- if current_version %} +
+ + Other Versions + v: {{ current_version.name }} + + +
+ {%- if versions.tags %} +
+
Tags
+ {%- for item in versions.tags %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} + {%- if versions.branches %} +
+
Branches
+ {%- for item in versions.branches %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} +
+
+{%- endif %} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 28288bf..0131ab8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,31 +27,42 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ - "sphinx.ext.autodoc", - "sphinx_autodoc_typehints", - "sphinx.ext.ifconfig", - "sphinx.ext.autosummary", - "sphinx.ext.doctest", - "sphinx.ext.todo", - "sphinx.ext.viewcode", - "sphinx.ext.napoleon", - "sphinx.ext.githubpages", - "sphinx.ext.inheritance_diagram", - "sphinx.ext.graphviz", - "sphinx_copybutton", - "sphinx-prompt", - "notfound.extension", - "versionwarning.extension", + "sphinx.ext.autodoc", # for autodoc + "sphinx.ext.ifconfig", # for if statements + "sphinx.ext.autosummary", # for autosummary + "sphinx.ext.doctest", # for doctest + "sphinx.ext.todo", # for todo list + "sphinx.ext.viewcode", # for source code + "sphinx.ext.napoleon", # for google style docstrings + "sphinx.ext.githubpages", # for github pages + "sphinx.ext.inheritance_diagram", # for inheritance diagrams + "sphinx.ext.graphviz", # for graphviz + "sphinx.ext.mathjax", # for math + "sphinxcontrib.spelling", # for spell check + "sphinx_autodoc_typehints", # for type hints + "sphinx_autodoc_annotation", # for annotations + "sphinx_copybutton", # for copy button + "sphinx-prompt", # for prompt + "notfound.extension", # for 404 page + "versionwarning.extension", # for version warning + "recommonmark", # for markdown + "nbsphinx", # for notebooks ] templates_path = ["_templates"] -source_suffix = ".rst" +html_sidebars = { + "**": [ + "_templates/versions.html", + ], +} + +source_suffix = [".rst", ".md"] # The master toctree document. master_doc = "index" language = "en" -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"] # -- Options for HTML output ------------------------------------------------- @@ -59,6 +70,26 @@ html_theme = "sphinx_rtd_theme" html_static_path = ["_static"] +html_css_files = ["custom.css"] +html_show_sourcelink = False +html_show_sphinx = False +html_copy_source = False +html_show_copyright = True +html_use_index = True +# html +html_theme_options = { + "canonical_url": "", + "display_version": True, + "prev_next_buttons_location": "bottom", + "style_external_links": True, + "style_nav_header_background": "white", + # Toc options + "collapse_navigation": False, + "sticky_navigation": True, + "navigation_depth": 4, + "includehidden": True, + "titles_only": False, +} # generate autosummary even if no references autosummary_generate = True @@ -77,7 +108,8 @@ "private-members": True, "exclude-members": "__weakref__", "show-inheritance": True, - "inherited-members": False, + "inherited-members": True, + "ignore-module-all": True, } # coverage @@ -88,17 +120,6 @@ pygments_style = "sphinx" highlight_language = "python3" -# html -html_theme_options = { - "navigation_depth": 4, - "collapse_navigation": False, - "sticky_navigation": True, - "includehidden": True, - "titles_only": False, - "display_version": True, -} - - # napoleon napoleon_numpy_docstring = True diff --git a/docs/index.rst b/docs/index.rst index 70e1993..07e4e87 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,9 +7,13 @@ Welcome to pathfinding3d's documentation! ========================================= .. toctree:: - :maxdepth: 2 + :maxdepth: 3 :caption: Contents: + Pathfinding3D <./INTRO.md> + Installation <./INSTALL.md> + Usage <./USAGE.md> + Change Log <./CHANGELOG.md> modules diff --git a/docs/pathfinding3d.core.rst b/docs/pathfinding3d.core.rst index cb57465..c0cbc31 100644 --- a/docs/pathfinding3d.core.rst +++ b/docs/pathfinding3d.core.rst @@ -1,6 +1,11 @@ pathfinding3d.core package ========================== +.. automodule:: pathfinding3d.core + :members: + :undoc-members: + :show-inheritance: + Submodules ---------- @@ -51,11 +56,3 @@ pathfinding3d.core.world module :members: :undoc-members: :show-inheritance: - -Module contents ---------------- - -.. automodule:: pathfinding3d.core - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/pathfinding3d.finder.rst b/docs/pathfinding3d.finder.rst index 56e8fc8..88ee088 100644 --- a/docs/pathfinding3d.finder.rst +++ b/docs/pathfinding3d.finder.rst @@ -1,6 +1,11 @@ pathfinding3d.finder package ============================ +.. automodule:: pathfinding3d.finder + :members: + :undoc-members: + :show-inheritance: + Submodules ---------- @@ -67,11 +72,3 @@ pathfinding3d.finder.msp module :members: :undoc-members: :show-inheritance: - -Module contents ---------------- - -.. automodule:: pathfinding3d.finder - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/pathfinding3d.rst b/docs/pathfinding3d.rst index a111e7c..ba64125 100644 --- a/docs/pathfinding3d.rst +++ b/docs/pathfinding3d.rst @@ -1,6 +1,11 @@ pathfinding3d package ===================== +.. automodule:: pathfinding3d + :members: + :undoc-members: + :show-inheritance: + Subpackages ----------- @@ -9,11 +14,3 @@ Subpackages pathfinding3d.core pathfinding3d.finder - -Module contents ---------------- - -.. automodule:: pathfinding3d - :members: - :undoc-members: - :show-inheritance: diff --git a/pathfinding3d/version.txt b/pathfinding3d/version.txt index a2268e2..60a2d3e 100644 --- a/pathfinding3d/version.txt +++ b/pathfinding3d/version.txt @@ -1 +1 @@ -0.3.1 \ No newline at end of file +0.4.0 \ No newline at end of file diff --git a/setup.cfg b/setup.cfg index e5c00ce..738a327 100644 --- a/setup.cfg +++ b/setup.cfg @@ -36,7 +36,7 @@ disable = missing-docstring, too-many-arguments, too-many-branches, # many functions will naturally have unused arguments. - unused-argument, + unused-argument, [pylint.FORMAT] max-line-length = 120 diff --git a/setup.py b/setup.py index 68e02c4..48326d6 100644 --- a/setup.py +++ b/setup.py @@ -10,31 +10,42 @@ setup( name="pathfinding3d", description="Pathfinding algorithms in 3D (based on python-pathfinding)", - url="https://github.com/harisankar95/python-pathfinding-3D", + url="https://github.com/harisankar95/pathfinding3D", version=__version__, license="MIT", author="Harisankar Babu", - keywords=["pathfinding", "python"], + keywords=["pathfinding", "pathplanning", "python", "3D", "A*", "Dijkstra"], classifiers=[ + "Development Status :: 3 - Alpha", "License :: OSI Approved :: MIT License", "Natural Language :: English", "Operating System :: OS Independent", - "Programming Language :: Python", + "Programming Language :: Python :: 3.8", ], packages=[package for package in find_packages() if package.startswith("pathfinding3d")], package_data={"pathfinding3d": ["version.txt"]}, install_requires=["numpy"], + extras_require={ + "dev": [ + "black", + "pytest", + "coverage", + "sphinx<=6.2.1", + "sphinx_rtd_theme", + "recommonmark", + "nbsphinx", + "sphinx-autodoc-typehints", + "sphinx-copybutton", + "sphinx-prompt", + "sphinx-notfound-page", + "sphinx-version-warning", + "sphinxcontrib-spelling", + "sphinx-autodoc-annotation", + ] + }, tests_require=[ - "numpy", "pytest", "coverage", - "sphinx<=6.2.1", - "sphinx_rtd_theme", - "sphinx-autodoc-typehints", - "sphinx-copybutton", - "sphinx-prompt", - "sphinx-notfound-page", - "sphinx-version-warning", ], min_python_version="3.8", )