Repository navigation
docs: reorganize the method reference by task, docstring pass, new diagram - #45
Merged
Merged
Conversation
DGraph/UGraph and DVertex/UVertex share almost their entire interface via _BaseGraph/BaseVertex, so documenting each subclass with :inherited-members: duplicated the full method list on every page. Split the common interface into task-based pages instead (construction, adding/removing vertices and edges, analysis, representations, visualization, path planning), each pulling specific members via automethod/autoproperty to avoid duplicate object-description warnings. Subclass pages now cover only what's actually different (DGraph/UGraph have no public members of their own; DVertex/ UVertex override only connect()). Also merges edge.rst and the vertex-specifics pages under a combined "Edges & Vertices" heading, and removes PGraph.rst/modules.rst, orphaned sphinx-quickstart/apidoc leftovers that were never wired into the toctree and were the source of most duplicate-object warnings in a full build. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- Introduction and API details are documents, so each shows in the sidebar with its sub-headings indented (navigation_depth 3, collapse_navigation off) - every method page opens with an autosummary table of its methods, with the one-line summary and a link to the entry below it - add Introduction, API details and Exporting a graph pages, with inheritance diagrams for the graph, vertex and edge classes on the common page - fold DGraph/UGraph into the construction page and remove the dgraph and ugraph pages that documented the same classes a second time - drop the display_version theme option, which sphinx_rtd_theme no longer accepts The build has no warnings and no runblock errors. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Docstrings only (the code is unchanged apart from the docstrings, checked by comparing the AST with docstrings removed). - document the behaviour with self-loops and parallel edges, and the exceptions each method raises - cross-reference the related methods: component/samecomponent/nc and the degree family (degree, connectivity, average_degree, BaseVertex.degree) - connectivity() and BaseVertex.edges() now say which edges they return for each graph kind, and that an undirected self-loop counts twice - vertex_class/edge_class properties say they are set by the constructor - examples that show a figure use block=None, so they no longer emit the non-interactive-backend warning that runblock reports as an error Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- add docs/figs/datastructures.svg, exported from the EazyDraw source, and move the source to docs/figs/ with the other figures - show it at the top of the Edges & Vertices page under 'Underlying data structures', followed by a short description, and split the page into that section and 'Working with vertices and edges directly' - remove the 'Under the hood' section from the README, which embedded the old PNG by URL docs/source/datastructures.png is kept for now because the wiki still links to it by URL. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Export with the font set to Outline, so the figure no longer depends on Avenir, Bradley Hand and Courier being installed. With live text a viewer without those fonts (anything but macOS) got a generic face and three callouts overflowed their boxes. The export writes path coordinates with nine decimal places, giving 1.2 MB. Rounded to three decimals, and only inside d= attributes, it is 708 KB (220 KB gzipped) and differs from the original in 94 of 4.4 million pixels at 2000 px wide. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The opening paragraph mentioned 'embedded coordinates' only in passing. Say that embedding is optional and what it enables: edge costs computed from the vertex positions with a metric, nearest-vertex lookup, A* with the metric as its heuristic, and plotting or export with the layout preserved. Drop 'not a plotting library', which contradicted that. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- BaseGraph, not _BaseGraph, in every autoclass/automethod/autosummary directive (67 references) - analysis.rst lists adjacent() and isadjacent(), the canonical names, and not the neighbours/neighbors/isneighbour aliases These need the API changes in the source, so the build reads the new code only after this branch is rebased onto them; against the 0.6.5-era source the names do not exist. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Laplacian is laplacian, _BaseGraph is BaseGraph, and the vertex pages list adjacent rather than neighbours. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Up to standards ✅🟢 Issues
|
| Metric | Results |
|---|---|
| Complexity | 0 |
| Duplication | 0 |
NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #45 +/- ##
=======================================
Coverage 94.79% 94.79%
=======================================
Files 3 3
Lines 1249 1249
=======================================
Hits 1184 1184
Misses 65 65 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The long-delayed documentation reorganization.
PGraph.py: parameter lists, cross-references between related methods (the degree / adjacent / edges families,incidenceswithadjacentandout_edges), runblock fixes (block=None,;to suppress output), and the new API throughout (adjacentcanonical,BaseGraph,laplacian, in-edges,edges()as a list).docs/figs/datastructures.svg(with its.ezdrawsource), shown in the Sphinx docs; the PNG stays for the wiki link.adjacent()is the headline name, the base class isBaseVertex, and the graph does list its edges.The preceding code PRs (#37 to #44) are merged, so the docs build against the new API: a full
sphinx-build -Egives no warnings.Notes
Written against
mainas of #44. Another documentation and diagram pass is planned once the single-vertex-class refactor lands.🤖 Generated with Claude Code