(doc) standardize documentation #2719
Conversation
WalkthroughThis pull request involves extensive documentation updates across multiple files in the pgRouting project. The changes primarily focus on standardizing documentation formatting, clarifying function statuses, updating function signatures, and making minor textual improvements. The modifications span various documentation files, touching on function descriptions, availability, signatures, and output columns across different routing algorithms and utility functions. Changes
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
⏰ Context from checks skipped due to timeout of 90000ms (1)
🔇 Additional comments (3)
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🔭 Outside diff range comments (4)
doc/contraction/pgr_contraction.rst (1)
Line range hint
42-42: Fix typo in the Description section.There's a typo in the word "Currently" (written as "Currnetly").
- - Currnetly there are two types of contraction methods + - Currently there are two types of contraction methodsdoc/withPoints/pgr_withPointsKSP.rst (3)
Line range hint
82-83: Standardize the result column references.There's an inconsistency in the documentation where some signatures reference |ksp-result| while others use |nksp-result|. This could confuse users about what columns to expect in the results. Please standardize to use the same reference throughout the document.
Also applies to: 141-142, 179-180, 217-218
Line range hint
304-314: Align with documentation standardization objectives.To meet the PR's standardization goals:
- Add periods at the end of descriptions in the Parameters table
- Remove bold formatting from parameter types that aren't actual parameters
Example fix for the Parameters table:
* - `Edges SQL`_ - ``TEXT`` - - `Edges SQL`_ query as described + - `Edges SQL`_ query as described. * - `Points SQL`_ - ``TEXT`` - - `Points SQL`_ query as described + - `Points SQL`_ query as described. * - **start vid** - - **ANY-INTEGER** + - ``ANY-INTEGER`` - - Identifier of the departure vertex + - Identifier of the departure vertex.
Line range hint
185-187: Enhance example descriptions for clarity.The example descriptions could be improved by:
- Consistently using math notation for points (e.g., :math:
1vs 1)- Clearly indicating all parameters being used in the example
- Using consistent formatting for parameter values
Example improvement:
-:Example: Get a path from point 1 and vertex 6 to point 3 and vertex 1 on a **directed** - graph with **left** side driving and **heap_paths** set to **True** +:Example: Get a path from point :math:`1` and vertex :math:`6` to point :math:`3` and vertex :math:`1` on a directed + graph with left side driving and ``heap_paths`` set to ``true``.Also applies to: 224-226
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (53)
NEWS.md(5 hunks)doc/allpairs/pgr_floydWarshall.rst(1 hunks)doc/allpairs/pgr_johnson.rst(1 hunks)doc/alpha_shape/pgr_alphaShape.rst(1 hunks)doc/astar/pgr_aStar.rst(2 hunks)doc/astar/pgr_aStarCost.rst(1 hunks)doc/astar/pgr_aStarCostMatrix.rst(1 hunks)doc/bdAstar/pgr_bdAstar.rst(2 hunks)doc/bdAstar/pgr_bdAstarCost.rst(1 hunks)doc/bdAstar/pgr_bdAstarCostMatrix.rst(1 hunks)doc/bdDijkstra/pgr_bdDijkstra.rst(2 hunks)doc/bdDijkstra/pgr_bdDijkstraCost.rst(1 hunks)doc/bdDijkstra/pgr_bdDijkstraCostMatrix.rst(1 hunks)doc/components/pgr_articulationPoints.rst(1 hunks)doc/components/pgr_biconnectedComponents.rst(1 hunks)doc/components/pgr_bridges.rst(1 hunks)doc/components/pgr_connectedComponents.rst(1 hunks)doc/components/pgr_strongComponents.rst(1 hunks)doc/contraction/pgr_contraction.rst(1 hunks)doc/dijkstra/pgr_dijkstra.rst(2 hunks)doc/dijkstra/pgr_dijkstraCost.rst(1 hunks)doc/dijkstra/pgr_dijkstraCostMatrix.rst(1 hunks)doc/driving_distance/pgr_drivingDistance.rst(1 hunks)doc/ksp/pgr_KSP.rst(1 hunks)doc/lineGraph/pgr_lineGraph.rst(1 hunks)doc/lineGraph/pgr_lineGraphFull.rst(1 hunks)doc/max_flow/pgr_boykovKolmogorov.rst(1 hunks)doc/max_flow/pgr_edgeDisjointPaths.rst(1 hunks)doc/max_flow/pgr_edmondsKarp.rst(1 hunks)doc/max_flow/pgr_maxCardinalityMatch.rst(1 hunks)doc/max_flow/pgr_maxFlow.rst(1 hunks)doc/max_flow/pgr_pushRelabel.rst(1 hunks)doc/mincut/pgr_stoerWagner.rst(1 hunks)doc/spanningTree/pgr_kruskal.rst(1 hunks)doc/spanningTree/pgr_kruskalBFS.rst(1 hunks)doc/spanningTree/pgr_kruskalDD.rst(1 hunks)doc/spanningTree/pgr_kruskalDFS.rst(1 hunks)doc/spanningTree/pgr_prim.rst(1 hunks)doc/spanningTree/pgr_primBFS.rst(1 hunks)doc/spanningTree/pgr_primDD.rst(1 hunks)doc/spanningTree/pgr_primDFS.rst(1 hunks)doc/src/release_notes.rst(4 hunks)doc/topology/pgr_analyzeGraph.rst(1 hunks)doc/topology/pgr_analyzeOneWay.rst(1 hunks)doc/topology/pgr_createTopology.rst(1 hunks)doc/topology/pgr_createVerticesTable.rst(1 hunks)doc/topology/pgr_nodeNetwork.rst(1 hunks)doc/trsp/pgr_trsp.rst(2 hunks)doc/tsp/pgr_TSP.rst(1 hunks)doc/tsp/pgr_TSPeuclidean.rst(1 hunks)doc/version/pgr_full_version.rst(1 hunks)doc/version/pgr_version.rst(1 hunks)doc/withPoints/pgr_withPointsKSP.rst(1 hunks)
🧰 Additional context used
🪛 Markdownlint (0.37.0)
NEWS.md
1372-1372: Expected: 1; Actual: 2
Multiple consecutive blank lines
(MD012, no-multiple-blanks)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: documentation (en)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (61)
doc/topology/pgr_analyzeGraph.rst (1)
25-25: LGTM! Documentation standardization looks good.The addition of a period after "Official function" aligns with the PR objectives of standardizing documentation formatting and improves readability by making it a complete sentence.
doc/components/pgr_articulationPoints.rst (1)
28-28: LGTM! Documentation standardization looks good.The change aligns perfectly with the PR objectives by:
- Removing bold formatting
- Adding a period at the end of the sentence
- Standardizing the documentation format in the Availability section
doc/contraction/pgr_contraction.rst (2)
30-30: LGTM! Documentation standardization looks good.The addition of the period at the end of the sentence follows the standardization guidelines mentioned in the PR objectives.
Line range hint
1-300: Documentation changes align with PR objectives.The modifications successfully implement the standardization goals:
- Proper period usage at the end of sentences
- No unnecessary bold formatting
doc/max_flow/pgr_boykovKolmogorov.rst (4)
26-27: LGTM! Clear and well-formatted signature documentation.The new proposed signature is clearly documented with proper formatting and punctuation.
32-32: LGTM! Clear status documentation.The function's promotion to official status is clearly documented with proper punctuation.
37-37: LGTM! Clear status documentation.The function's historical promotion to proposed status is clearly documented with proper punctuation.
41-41: LGTM! Standardized formatting.The experimental status is documented with standardized formatting and proper punctuation.
doc/spanningTree/pgr_kruskal.rst (1)
26-26: LGTM! Documentation standardization applied correctly.The formatting change aligns with the PR objectives by removing bold from "Official" and ensuring the sentence ends with a period.
doc/spanningTree/pgr_prim.rst (1)
26-26: LGTM! Documentation standardization applied correctly.The formatting change aligns with the PR objectives by removing bold from "Official" and ensuring the sentence ends with a period.
doc/spanningTree/pgr_primDD.rst (1)
33-33: LGTM! Documentation standardization applied correctly.The formatting change aligns with the PR objectives by removing bold from "Official" and ensuring the sentence ends with a period.
doc/spanningTree/pgr_kruskalDD.rst (1)
34-34: LGTM! Documentation standardization applied correctly.The formatting change aligns with the PR objectives by removing bold from "Official" and ensuring the sentence ends with a period.
doc/spanningTree/pgr_primDFS.rst (1)
34-34: LGTM! Documentation standardization applied correctly.The formatting change aligns with the PR objectives by removing bold from "Official" and ensuring the sentence ends with a period.
doc/spanningTree/pgr_primBFS.rst (1)
34-34: Documentation standardization looks good.The removal of bold formatting from "official" aligns with the PR objectives for standardizing documentation.
doc/spanningTree/pgr_kruskalBFS.rst (1)
34-34: Documentation standardization looks good.The changes maintain consistency with other files in the documentation.
doc/spanningTree/pgr_kruskalDFS.rst (1)
34-34: Documentation standardization looks good.The changes maintain consistency with the standardization efforts across the documentation.
doc/dijkstra/pgr_dijkstraCostMatrix.rst (1)
26-26: LGTM! The documentation update aligns with standardization goals.The change follows the standardization pattern by:
- Removing bold formatting
- Adding a period at the end of the sentence
- Using consistent phrasing "Function promoted to official"
Let's verify this standardization is consistent across other similar files:
✅ Verification successful
Verified: Documentation follows consistent formatting pattern
The change follows the standard format used across the codebase for promoted functions, matching the pattern used in other files like
pgr_bdDijkstra.rst,pgr_aStar.rst, and other recently promoted functions.🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Description: Check for consistency in function status formatting across documentation # Expected: All similar status lines should follow the same format # Search for any variations of status formatting in documentation rg -t rst "(\*\*Official\*\* function|Function promoted to official|Official function)" doc/Length of output: 3074
doc/withPoints/pgr_withPointsKSP.rst (1)
Line range hint
36-44: LGTM! Clear documentation of API changes.The documentation clearly outlines:
- New proposed signatures for various use cases (One to Many, Many to One, Many to Many, Combinations)
- Deprecation notice for the old signature format
doc/version/pgr_version.rst (1)
31-31: LGTM! Documentation standardization applied correctly.The change aligns with the PR objectives by removing bold formatting and maintaining the period at the end of the sentence.
doc/version/pgr_full_version.rst (1)
25-25: LGTM! Documentation standardization applied correctly.The change aligns with the PR objectives by removing bold formatting and maintaining the period at the end of the sentence.
doc/components/pgr_bridges.rst (1)
26-26: LGTM! Documentation standardization applied correctly.The change aligns with the PR objectives by using standard formatting and maintaining the period at the end of the sentence.
doc/allpairs/pgr_johnson.rst (1)
31-31: LGTM! Documentation standardization applied correctly.The change aligns with the PR objectives by removing bold formatting and maintaining the period at the end of the sentence.
doc/components/pgr_strongComponents.rst (1)
31-31: LGTM! Documentation standardization applied correctly.The change aligns with the PR objectives by using standard formatting and maintaining the period at the end of the sentence.
doc/allpairs/pgr_floydWarshall.rst (1)
31-31: LGTM! Documentation standardizationThe addition of a period after "Official function" aligns with the documentation standardization objective.
doc/alpha_shape/pgr_alphaShape.rst (1)
39-39: LGTM! Documentation standardizationThe addition of a period after "Official function" maintains consistency with the documentation standards.
doc/bdDijkstra/pgr_bdDijkstraCostMatrix.rst (1)
27-27: LGTM! Improved status descriptionThe change to "Function promoted to official." provides clearer status information while maintaining documentation standards.
doc/components/pgr_biconnectedComponents.rst (1)
31-31: LGTM! Consistent status descriptionThe update to "Function promoted to official." maintains consistency with other function documentation while following standardization guidelines.
doc/components/pgr_connectedComponents.rst (1)
31-31: LGTM! Documentation standardizationThe update to "Function promoted to official." aligns with the standardization effort across the documentation.
doc/astar/pgr_aStarCostMatrix.rst (1)
27-27: LGTM!The formatting change aligns with the documentation standardization objective.
doc/bdAstar/pgr_bdAstarCostMatrix.rst (1)
26-26: LGTM!The formatting change maintains consistency with other documentation files.
doc/max_flow/pgr_maxCardinalityMatch.rst (1)
41-41: LGTM!The formatting changes consistently apply the standardization across different function status types (official, proposed, experimental).
Also applies to: 46-46, 50-50
doc/mincut/pgr_stoerWagner.rst (1)
29-29: LGTM!The formatting change aligns with the standardization pattern seen in other files.
doc/driving_distance/pgr_drivingDistance.rst (1)
38-38: LGTM!The formatting changes align with the documentation standardization objective.
Also applies to: 43-43
doc/topology/pgr_analyzeOneWay.rst (1)
28-28: Documentation standardization looks good.The status description has been standardized to use consistent formatting.
doc/max_flow/pgr_edmondsKarp.rst (2)
26-27: Signature formatting looks good.The addition of the colon after "New proposed signature" improves readability and maintains consistency.
32-32: Function status descriptions are properly standardized.The status descriptions have been updated to use consistent phrasing across different versions.
Also applies to: 37-37, 41-41
doc/max_flow/pgr_pushRelabel.rst (1)
26-27: Documentation updates maintain consistency.The changes to signature formatting and status descriptions align with the standardization effort across the documentation.
Also applies to: 32-32, 37-37
doc/max_flow/pgr_maxFlow.rst (1)
26-27: Documentation standardization is consistent.The changes to signature formatting and status descriptions maintain consistency with other max_flow documentation files.
Also applies to: 32-32, 36-36
doc/tsp/pgr_TSPeuclidean.rst (1)
41-41: Status description standardization is appropriate.The update to the function status description maintains consistency with the documentation standardization effort.
doc/bdDijkstra/pgr_bdDijkstra.rst (1)
32-32: Documentation standardization looks good!The changes improve clarity by:
- Using consistent phrasing for function status
- Removing unnecessary bold formatting
- Maintaining a standard format across version history entries
Also applies to: 50-50
doc/max_flow/pgr_edgeDisjointPaths.rst (1)
33-33: Documentation updates are consistent!The changes successfully:
- Standardize function status descriptions
- Maintain clear version progression (experimental → proposed → official)
- Follow the project-wide documentation format
Also applies to: 37-37, 41-41
doc/dijkstra/pgr_dijkstraCost.rst (1)
34-34: Documentation standardization is appropriate!The change maintains consistency by using the standard "Official function" format, removing redundant qualifiers.
doc/trsp/pgr_trsp.rst (1)
31-31: Documentation formatting is improved!The changes enhance readability by:
- Adding appropriate punctuation
- Maintaining consistent function status descriptions
Also applies to: 55-55
doc/tsp/pgr_TSP.rst (1)
43-43: Documentation standardization is consistent!The change maintains the standard format for function status descriptions across the project.
doc/astar/pgr_aStarCost.rst (1)
32-32: LGTM!The change standardizes the documentation format by removing bold formatting and maintaining consistency in function status description.
doc/bdAstar/pgr_bdAstarCost.rst (1)
32-32: LGTM!The change maintains consistency with other files by standardizing the function status description.
doc/astar/pgr_aStar.rst (2)
39-39: LGTM!The change standardizes the documentation format by using consistent phrasing for function status.
57-57: LGTM!The change aligns with PR objectives by removing bold formatting while maintaining the meaning.
doc/bdAstar/pgr_bdAstar.rst (3)
39-39: LGTM!The change standardizes the documentation format by using consistent phrasing for function status.
43-43: LGTM!The change maintains consistency by removing bold formatting from the proposed signatures description.
55-55: LGTM!The change aligns with PR objectives by removing bold formatting while maintaining the meaning.
doc/topology/pgr_createVerticesTable.rst (1)
26-26: LGTM!The change standardizes the documentation format by removing bold formatting while maintaining the meaning.
doc/topology/pgr_createTopology.rst (1)
26-26: Documentation standardization looks good!The formatting change aligns with the standardization goals, improving consistency across the documentation.
doc/ksp/pgr_KSP.rst (1)
45-45: Documentation standardization looks good!The formatting change maintains consistency with other documentation updates.
doc/topology/pgr_nodeNetwork.rst (1)
41-41: Documentation standardization looks good!The formatting change follows the established pattern, maintaining consistency across the documentation.
doc/lineGraph/pgr_lineGraphFull.rst (1)
30-30: Documentation standardization looks good!The formatting change aligns with the standardization pattern, improving consistency while maintaining clarity.
doc/lineGraph/pgr_lineGraph.rst (1)
35-35: Documentation standardization looks good!The formatting change maintains consistency with the standardization pattern across the documentation.
doc/dijkstra/pgr_dijkstra.rst (2)
40-40: LGTM! Documentation standardization.The change improves consistency by removing bold formatting and adding a period.
56-56: LGTM! Documentation standardization.The change improves consistency by removing bold formatting and adding a period.
NEWS.md (1)
253-253: LGTM! Documentation standardization.The addition of a colon improves readability and maintains consistent formatting.
doc/src/release_notes.rst (1)
1376-1376: LGTM! Documentation standardization.The changes improve consistency in rubric formatting:
- Added periods where appropriate
- Added colons for lists
- Standardized capitalization
Also applies to: 1464-1464, 1469-1469, 1481-1481
Changes proposed in this pull request:
@pgRouting/admins
Summary by CodeRabbit
Based on the comprehensive summary of changes, here are the updated release notes:
Documentation Updates
Function Enhancements
pgr_dijkstra(Combinations)pgr_withPointsKSP(One to Many, Many to One, Many to Many, Combinations)pgr_trsp(Multiple Signature Variations)start_vidandend_vidDeprecation Notices
Minor Improvements