Repository navigation
docs: expand existing Python API documentation without code changes - #71
Merged
Merged
Conversation
Adapt numpydoc content conventions to the existing Markdown reference, including object-kind-aware coverage, stable symbol anchors, numerical semantics, ownership, errors, and the optional cffi interface. Add independent example execution, documentation-check regression tests, and explicit checkout/released package selection in documentation CI. No numerical kernels or public Python API behavior are changed.
Restore documentation CI and Python validation tooling to upstream versions. Retain all changes under docs/ without further modification.
Retain every line of the existing API reference, NumPy guide, contributor notes, and numerical conventions while supplementing verified contracts, worked examples, numerical behavior, and ownership explanations. Keep the original API heading signatures, required Markdown sections, existing Python documentation validator, and workflow configuration. Demonstrate irreversible shutdown as non-executable text so the existing sequential example runner remains usable.
LunaStev
changed the title
Retain existing headings and source-derived signatures; add Markdown-only symbol anchors so reference and NumPy-guide links resolve under MkDocs.
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
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
Expand the existing Python API documentation without replacing or deleting any original documentation.
This PR changes only four Markdown files under
docs/. Every original line is preserved. No Python sources, numeric kernels, validation tools, MkDocs configuration, or GitHub Actions workflows are changed. The diff is 856 lines added, zero lines deleted.Documentation improvements
docs/reference/python.md: Add stable HTML anchors for supplementary links and detailed numerical, shape, ownership, lifetime, exception, and implementation notes to the existing public API entries while retaining their exact headings, original parameter tables, examples, and reference links. Include more worked examples for array conversion, matrix multiplication, reductions, reshaping, and exceptional conditions; document public exception and cffi attributes.docs/guides/numpy.md: Add a copy-versus-borrow comparison, negative-stride handling, view lifetimes, contiguous reshaping, and a NumPy comparison example. Keep the original tutorials intact.docs/explanation/numerical-conventions.md: Explain Python reduction and matrix-product numerical behavior and the distinction between mathematical definitions and implementation guarantees.docs/contributing.md: Clarify documentation-only writing conventions, the existing Markdown schema, executable example expectations, and the current checker’s limitations.New explanations are based on the current Python bindings and C/Haskell numerical boundary; no new Python functionality or general accuracy guarantee is claimed. Existing numpydoc and Diátaxis guidance is retained.
Scope and verification
Parameters,Returns, andSee alsosections are retained.shutdown()documentation in a non-executabletextblock so the original sequential Python example checker is not disrupted.bb3ad5e.Workflow note: The existing
ValidateandPython wheelsworkflows intentionally usepaths-ignorefordocs/**; only theDocumentationworkflow is expected to run on this documentation-only commit. Their absence is not evidence that workflows were removed.This PR does not modify code or CI configuration and does not merge the PR automatically.