Add modern type hints and reST docstrings throughout PGraph.py

.github/workflows/ci.yml

@@ -25,6 +25,27 @@ jobs:
       - name: Test with pytest
         run: pytest
 
+  mypy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+      - name: Run mypy
+        # Informational only for now: the type-hinting pass surfaced a
+        # baseline of pre-existing design tensions (Liskov-incompatible
+        # overrides, embedded-graph invariants not visible to the type
+        # checker) that are tracked separately, not fixed here. Don't fail
+        # the build on them yet.
+        continue-on-error: true
+        run: mypy src/pgraph/PGraph.py
+
   codecov:
     needs: unittest
     runs-on: ubuntu-latest
@@ -62,7 +83,6 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install .[docs]
-          pip install git+https://github.com/petercorke/sphinx-autorun.git
           sudo apt-get update
           sudo apt-get install -y graphviz
       - name: Build docs

docs/source/PGraph.rst

@@ -1,7 +1,7 @@
 PGraph module
 =============
 
-.. automodule:: PGraph
+.. automodule:: pgraph.PGraph
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/conf.py

@@ -30,13 +30,33 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "sphinx.ext.mathjax",
     "sphinx.ext.coverage",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.inheritance_diagram",
+    "sphinx_autodoc_typehints",
+    "sphinx_copybutton",
+    "sphinx_pyrunblock",
+    "sphinx_codeautolink",
 ]
 
+autosummary_generate = True
+
+# copybutton configuration: strip >>> and ... prompts when copying
+copybutton_prompt_text = r">>> |\.\.\. "
+copybutton_prompt_is_regexp = True
+
+# sphinx_codeautolink: link names in code blocks to their API docs
+codeautolink_autodoc_inject = False
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
+
 html_theme_options = {
     "logo_only": False,
     "display_version": True,

docs/source/dgraph.rst

@@ -2,7 +2,7 @@ Directed graph
 --------------
 
 
-.. autoclass:: PGraph.DGraph
+.. autoclass:: pgraph.PGraph.DGraph
    :undoc-members:
    :show-inheritance:
    :inherited-members:

docs/source/dvertex.rst

@@ -1,7 +1,7 @@
 Directed graph vertex
 ---------------------
 
-.. autoclass:: PGraph.DVertex
+.. autoclass:: pgraph.PGraph.DVertex
    :undoc-members:
    :show-inheritance:
    :inherited-members:

docs/source/edge.rst

@@ -1,7 +1,7 @@
 Edge
 ----
 
-.. autoclass:: PGraph.Edge
+.. autoclass:: pgraph.PGraph.Edge
    :undoc-members:
    :show-inheritance:
    :inherited-members:

docs/source/matrices.rst

@@ -3,5 +3,5 @@ Convert graph to matrix form
 
 These methods convert a graph to a matrix representation .
 
-.. autoclass:: PGraph.PGraph
+.. autoclass:: pgraph.PGraph.PGraph
     :members: distance, adjacency, degree, incidence, Laplacian

docs/source/planning.rst

@@ -3,5 +3,5 @@ Path planning
 
 These methods find optimal paths from a start vertex to a goal vertex.
 
-.. autoclass:: PGraph.PGraph
+.. autoclass:: pgraph.PGraph.PGraph
    :members: path_BFS, path_UCS, path_Astar

docs/source/ugraph.rst

@@ -2,7 +2,7 @@ Undirected graph
 ----------------
 
 
-.. autoclass:: PGraph.UGraph
+.. autoclass:: pgraph.PGraph.UGraph
    :undoc-members:
    :show-inheritance:
    :inherited-members:

docs/source/uvertex.rst

@@ -1,7 +1,7 @@
 Undirected graph vertex
 -----------------------
 
-.. autoclass:: PGraph.UVertex
+.. autoclass:: pgraph.PGraph.UVertex
    :undoc-members:
    :show-inheritance:
    :inherited-members:

pyproject.toml

@@ -4,7 +4,7 @@ version = "0.6.4"
 authors = [{ name = "Peter Corke", email = "rvc@petercorke.com" }]
 description = "Mathematical graphs for Python"
 readme = "README.md"
-requires-python = ">=3.7"
+requires-python = ">=3.9"
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     # Indicate who your project is intended for
@@ -32,7 +32,7 @@ keywords = [
     "optimal path",
 ]
 
-dependencies = ["spatialmath-python", "numpy>=1.18.0", "scipy", "matplotlib"]
+dependencies = ["spatialmath-python", "numpy>=2.0", "scipy", "matplotlib"]
 
 [project.urls]
 
@@ -45,14 +45,16 @@ dependencies = ["spatialmath-python", "numpy>=1.18.0", "scipy", "matplotlib"]
 
 [project.optional-dependencies]
 
-dev = ["pytest", "pytest-cov"]
+dev = ["pytest", "pytest-cov", "mypy"]
 
 docs = [
     "sphinx",
     "recommonmark",
     "sphinx-rtd-theme",
-    "sphinx-autorun",
-    "sphinx-favicon",
+    "sphinx-autodoc-typehints",
+    "sphinx-copybutton",
+    "sphinx-pyrunblock",
+    "sphinx-codeautolink",
 ]
 
 [tool.pytest.ini_options]
@@ -72,3 +74,9 @@ target-version = ['py311']
 
 [tool.coverage.run]
 omit = []
+
+[tool.mypy]
+python_version = "3.9"
+ignore_missing_imports = true
+warn_unused_ignores = true
+warn_redundant_casts = true