From 4e2f8c478f3743219cf14cf049158790b1351c10 Mon Sep 17 00:00:00 2001 From: Hari Date: Wed, 22 Nov 2023 02:32:55 +0100 Subject: [PATCH] setup sphinx doc and codecov yaml --- .../workflows/test-and-publish-release.yml | 11 + .github/workflows/test-main.yml | 15 ++ codecov.yml | 4 + docs/Makefile | 20 ++ docs/conf.py | 191 ++++++++++++++++ docs/index.rst | 21 ++ docs/make.bat | 35 +++ docs/modules.rst | 7 + docs/pathfinding3d.core.rst | 61 ++++++ docs/pathfinding3d.finder.rst | 77 +++++++ docs/pathfinding3d.rst | 19 ++ pathfinding.ipynb | 204 ------------------ setup.py | 13 +- 13 files changed, 473 insertions(+), 205 deletions(-) create mode 100644 codecov.yml create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 docs/modules.rst create mode 100644 docs/pathfinding3d.core.rst create mode 100644 docs/pathfinding3d.finder.rst create mode 100644 docs/pathfinding3d.rst delete mode 100644 pathfinding.ipynb diff --git a/.github/workflows/test-and-publish-release.yml b/.github/workflows/test-and-publish-release.yml index b653798..ca1e695 100644 --- a/.github/workflows/test-and-publish-release.yml +++ b/.github/workflows/test-and-publish-release.yml @@ -43,6 +43,17 @@ jobs: file: ./coverage.xml flags: unittests + - name: Build docs + run: | + pip install sphinx sphinx_rtd_theme sphinx-autodoc-typehints sphinx-copybutton sphinx-prompt sphinx-notfound-page sphinx-version-warning + sphinx-build -b html docs/ ./public + + - name: Deploy docs + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./public + - name: Publish 📦 to PyPI env: TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }} diff --git a/.github/workflows/test-main.yml b/.github/workflows/test-main.yml index 7ffd36a..ffc4962 100644 --- a/.github/workflows/test-main.yml +++ b/.github/workflows/test-main.yml @@ -4,6 +4,10 @@ on: push: branches: - main + pull_request: + branches: + - main + jobs: test: name: Test @@ -42,3 +46,14 @@ jobs: CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} file: ./coverage.xml flags: unittests + + - name: Build docs + run: | + pip install sphinx sphinx_rtd_theme sphinx-autodoc-typehints sphinx-copybutton sphinx-prompt sphinx-notfound-page sphinx-version-warning + sphinx-build -b html docs/ ./public + + - name: Deploy docs + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./public diff --git a/codecov.yml b/codecov.yml new file mode 100644 index 0000000..bde3288 --- /dev/null +++ b/codecov.yml @@ -0,0 +1,4 @@ +coverage: + round: down + range: "60...80" + precision: 2 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..28288bf --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,191 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +import os +import sys + +sys.path.insert(0, os.path.abspath("..")) + +# read the version from version.txt +with open(os.path.join("../pathfinding3d", "version.txt"), encoding="utf-8") as file_handler: + __version__ = file_handler.read().strip() + + +project = "pathfinding3d" +copyright = "2023, Harisankar Babu" +author = "Harisankar Babu" +release = __version__ +version = __version__ + + +# -- General configuration --------------------------------------------------- +# 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", +] + +templates_path = ["_templates"] +source_suffix = ".rst" + +# The master toctree document. +master_doc = "index" +language = "en" + +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_rtd_theme" +html_static_path = ["_static"] + +# generate autosummary even if no references +autosummary_generate = True +autosummary_imported_members = True + +# autodoc +autodoc_mock_imports = [] +autodoc_typehints = "description" +autodoc_inherit_docstrings = True +autodoc_preserve_defaults = True +autodoc_default_options = { + "members": True, + "member-order": "bysource", + "special-members": "__init__", + "undoc-members": True, + "private-members": True, + "exclude-members": "__weakref__", + "show-inheritance": True, + "inherited-members": False, +} + +# coverage +coverage_show_missing_items = True +coverage_skip_undoc_in_source = True + +# syntax highlighting +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 + +# todo-section +todo_include_todos = False + +# inheritance diagrams +# smaller diagrams with rectangular nodes +inheritance_graph_attrs = { + "rankdir": "TB", + "size": '"6.0, 8.0"', + "fontsize": 12, + "ratio": "compress", + "bgcolor": "transparent", +} + +inheritance_node_attrs = { + "shape": "rect", + "fontsize": 12, + "color": "orange", + "style": "filled", + "fillcolor": "white", +} + +inheritance_edge_attrs = { + "arrowsize": 0.5, + "penwidth": 1.0, + "color": "orange", +} + +# graphviz +graphviz_output_format = "svg" +graphviz_dot_args = [ + "-Gbgcolor=transparent", + "-Nfontname=Helvetica", + "-Efontname=Helvetica", + "-Gfontname=Helvetica", + "-Gfontsize=12", + "-Nfontsize=12", + "-Efontsize=12", +] + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = "pathfinding3d-doc" + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements: dict = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. +latex_documents = [ + (master_doc, "pathfinding3d.tex", "pathfinding3d Documentation", "pathfinding3d Contributors", "manual"), +] + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, "pathfinding3d", "pathfinding3d Documentation", [author], 1)] + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. +texinfo_documents = [ + ( + master_doc, + "pathfinding3d", + "pathfinding3d Documentation", + author, + "pathfinding3d", + "One line description of project.", + "Miscellaneous", + ), +] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..70e1993 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,21 @@ +.. pathfinding3d documentation master file, created by + sphinx-quickstart on Wed Nov 22 02:19:54 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to pathfinding3d's documentation! +========================================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + modules + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..954237b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/modules.rst b/docs/modules.rst new file mode 100644 index 0000000..ab9b522 --- /dev/null +++ b/docs/modules.rst @@ -0,0 +1,7 @@ +pathfinding3d +============= + +.. toctree:: + :maxdepth: 4 + + pathfinding3d diff --git a/docs/pathfinding3d.core.rst b/docs/pathfinding3d.core.rst new file mode 100644 index 0000000..cb57465 --- /dev/null +++ b/docs/pathfinding3d.core.rst @@ -0,0 +1,61 @@ +pathfinding3d.core package +========================== + +Submodules +---------- + +pathfinding3d.core.diagonal\_movement module +-------------------------------------------- + +.. automodule:: pathfinding3d.core.diagonal_movement + :members: + :undoc-members: + :show-inheritance: + +pathfinding3d.core.grid module +------------------------------ + +.. automodule:: pathfinding3d.core.grid + :members: + :undoc-members: + :show-inheritance: + +pathfinding3d.core.heuristic module +----------------------------------- + +.. automodule:: pathfinding3d.core.heuristic + :members: + :undoc-members: + :show-inheritance: + +pathfinding3d.core.node module +------------------------------ + +.. automodule:: pathfinding3d.core.node + :members: + :undoc-members: + :show-inheritance: + +pathfinding3d.core.util module +------------------------------ + +.. automodule:: pathfinding3d.core.util + :members: + :undoc-members: + :show-inheritance: + +pathfinding3d.core.world module +------------------------------- + +.. automodule:: pathfinding3d.core.world + :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 new file mode 100644 index 0000000..56e8fc8 --- /dev/null +++ b/docs/pathfinding3d.finder.rst @@ -0,0 +1,77 @@ +pathfinding3d.finder package +============================ + +Submodules +---------- + +pathfinding3d.finder.a\_star module +----------------------------------- + +.. automodule:: pathfinding3d.finder.a_star + :members: + :undoc-members: + :show-inheritance: + +pathfinding3d.finder.best\_first module +--------------------------------------- + +.. automodule:: pathfinding3d.finder.best_first + :members: + :undoc-members: + :show-inheritance: + +pathfinding3d.finder.bi\_a\_star module +--------------------------------------- + +.. automodule:: pathfinding3d.finder.bi_a_star + :members: + :undoc-members: + :show-inheritance: + +pathfinding3d.finder.breadth\_first module +------------------------------------------ + +.. automodule:: pathfinding3d.finder.breadth_first + :members: + :undoc-members: + :show-inheritance: + +pathfinding3d.finder.dijkstra module +------------------------------------ + +.. automodule:: pathfinding3d.finder.dijkstra + :members: + :undoc-members: + :show-inheritance: + +pathfinding3d.finder.finder module +---------------------------------- + +.. automodule:: pathfinding3d.finder.finder + :members: + :undoc-members: + :show-inheritance: + +pathfinding3d.finder.ida\_star module +------------------------------------- + +.. automodule:: pathfinding3d.finder.ida_star + :members: + :undoc-members: + :show-inheritance: + +pathfinding3d.finder.msp module +------------------------------- + +.. automodule:: pathfinding3d.finder.msp + :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 new file mode 100644 index 0000000..a111e7c --- /dev/null +++ b/docs/pathfinding3d.rst @@ -0,0 +1,19 @@ +pathfinding3d package +===================== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + pathfinding3d.core + pathfinding3d.finder + +Module contents +--------------- + +.. automodule:: pathfinding3d + :members: + :undoc-members: + :show-inheritance: diff --git a/pathfinding.ipynb b/pathfinding.ipynb deleted file mode 100644 index 17992a2..0000000 --- a/pathfinding.ipynb +++ /dev/null @@ -1,204 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "A simple usage example to find a path using A*." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "metadata": {}, - "outputs": [], - "source": [ - "from pathfinding.core.diagonal_movement import DiagonalMovement\n", - "from pathfinding.core.grid import Grid\n", - "from pathfinding.finder.a_star import AStarFinder" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "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. In this example we like the algorithm to create a path from the upper left to the bottom right. To make it not to easy for the algorithm we added an obstacle in the middle, so it can not use the direct way. We ignore the weight for now, all fields have the same cost. Feel free to create a more complex map" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "metadata": {}, - "outputs": [], - "source": [ - "matrix = [\n", - " [1, 1, 1],\n", - " [1, 0, 1],\n", - " [1, 1, 1]\n", - "]" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "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." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "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 height is defined by the length of the outer list and the width by the length of the first list inside it." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "(3, 3)" - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "grid = Grid(matrix=matrix)\n", - "(grid.height, grid.width)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "we get the start (top-left) and endpoint (bottom-right) from the map:" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": {}, - "outputs": [], - "source": [ - "start = grid.node(0, 0)\n", - "end = grid.node(2, 2)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "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." - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [], - "source": [ - "finder = AStarFinder(diagonal_movement=DiagonalMovement.always)\n", - "path, runs = finder.find_path(start, end, grid)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "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." - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "operations: 5 path length: 4\n" - ] - } - ], - "source": [ - "print('operations:', runs, 'path length:', len(path))" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "+---+\n", - "|sx |\n", - "| #x|\n", - "| e|\n", - "+---+\n" - ] - } - ], - "source": [ - "print(grid.grid_str(path=path, start=start, end=end))" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "you can also print the path as tuple of x and y coordinates:" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "[(0, 0), (1, 0), (2, 1), (2, 2)]" - ] - }, - "execution_count": 8, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "path" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.6.3" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/setup.py b/setup.py index 40c0f32..68e02c4 100644 --- a/setup.py +++ b/setup.py @@ -24,6 +24,17 @@ packages=[package for package in find_packages() if package.startswith("pathfinding3d")], package_data={"pathfinding3d": ["version.txt"]}, install_requires=["numpy"], - tests_require=["numpy", "pytest", "coverage"], + 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", )