Repository navigation
docs: correct API facts and state contracts concisely - #566
Merged
Merged
Conversation
Describe the layout pipeline as it runs, state every rendering default in the API reference, show keyword-only arguments, and cut historical narrative from the contributing guide. Refs: #552
Rewrite the layout and routing docstrings in NumPy style, keep the equations and constraints the code relies on, and remove design history, review narrative and corpus figures stated as current fact. Refs: #552
Rewrite the model, port geometry, loop, station, deprecation and CLI docstrings in NumPy style, and take the CLI's crossing-style help default from argparse so it reports gap rather than arc. Refs: #552
State the gap crossing-style default, rewrite every flowsheet docstring in NumPy style, and replace review history and corpus figures with the rules the code relies on. Refs: #552
Rewrite every docstring and comment in pandid/units.py to NumPy style: short class contracts with parameters and raised errors, method docstrings throughout, and short comments for placement claims. Remove issue, version and corpus history that no longer guides a maintainer. Code is unchanged; the AST matches the previous revision apart from docstrings. Refs: #552
Rewrite the documentation of pandid/spec.py, pandid/document.py and pandid/validate.py in NumPy style, cutting issue, version and corpus history to the constraint each still explains. Shorten the device docstrings and comments in scripts/gen_devices.py, add a parameters note and stub docstrings to its output, and regenerate pandid/devices.py. Module code is unchanged; the generator's logic changes only in the docstring text it emits. Refs: #552
Rewrite the documentation of pandid/render/svg.py in NumPy style and cut issue, corpus and review history to the constraint each comment still explains. State "gap" as the crossing-style default in the CROSSING_STYLES notes and the SvgRenderer.render docstring, which called "arc" the default. Code is unchanged; the AST matches the previous revision apart from docstrings. Refs: #552
Rewrite the documentation of pandid/render/symbols.py and pandid/render/iso_parts.py in NumPy style. Give SymbolRegistry and its public methods full contracts, move the Symbol field notes into an Attributes section, and cut issue, corpus and drafting history while keeping ISO item and registration references, grid coordinates and provenance. Code is unchanged; the AST matches the previous revision apart from docstrings. Refs: #552
Rewrite the documentation of pandid/render/drawio.py in NumPy style, cutting issue, version and corpus history to the mxGraph or draw.io behaviour each comment still explains. Give DrawioRenderer.render a full parameter section with "gap" as the crossing-style default, and point the _Approximation docstring at the _BUILTIN_SHAPES set in tests/test_drawio.py instead of an undefined module name. Code is unchanged; the AST matches the previous revision apart from docstrings. Refs: #552
Rewrite the documentation of pandid/render/furniture.py, export.py, debug.py, weights.py, escape.py and render/__init__.py in NumPy style, cutting issue, corpus and drafting history while keeping the ISO citations and measured layout facts. Code is unchanged; the AST matches the previous revision apart from docstrings. Refs: #552
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
Corrects the documented API facts that disagreed with the code: the crossing-style default, the placement algorithm in CONTRIBUTING, and a broken cross-reference. It also rewrites the package's documentation as concise NumPy-style contracts, without issue, review or corpus history. Documentation only: no behaviour, drawing or golden changes.
Related Issues
Closes #552
Refs: #547
Changes
"gap"indocs/api.md, theFlowsheetrender entry points, both renderers and the CLI help.drawio.py's_BUILTIN_SHAPESreference now points attests/test_drawio.py.layout/claims.py,COL_GAPand the rollback docstring among them.flowsheet,units,spec,document,validateand render modules.pandid/devices.pyis regenerated fromscripts/gen_devices.py.How to Test
Run the suite and gates:
python3 -m pytest -q python3 -m ruff check . python3 -m ruff format --check tests python3 -m mypy pandid python3 -m pyright pandidCheck the crossing-style default as an API consumer:
Confirm the generated module matches its generator:
Evidence
180a2cf)pandid/__init__)(default: gap).git diff --checkare clean. Pyright reports 0 errors plus the existing__all__warning.Checklist
mainand the branch is mergeable🤖 Generated with Claude Code