Docs: fix examples, fill API reference gaps, document gotchas - #602
Open
eriknw wants to merge 6 commits into
Open
Docs: fix examples, fill API reference gaps, document gotchas#602eriknw wants to merge 6 commits into
eriknw wants to merge 6 commits into
Conversation
eriknw
marked this pull request as ready for review
August 4, 2026 16:07
eriknw
force-pushed
the
22-docs
branch
2 times, most recently
from
August 5, 2026 03:18
68a6ae8 to
f1aa8de
Compare
eriknw
force-pushed
the
22-docs
branch
2 times, most recently
from
August 6, 2026 20:36
4eaa2d5 to
e7cd805
Compare
eriknw
force-pushed
the
22-docs
branch
2 times, most recently
from
August 7, 2026 02:48
69065d5 to
906b173
Compare
The README UDF example imported unary but then used Vector without importing it, so the snippet as published raised NameError: name 'Vector' is not defined. Add Vector to the import; the copy in docs/user_guide/udf.rst was already correct. Also a new docs/api_reference/types.rst, wired into the reference toctree, surfacing DataType's JIT introspection properties (jit_c_name, jit_c_definition) and the dtypes register_new / register_anonymous helpers. None of that had an API reference entry.
Matrix.from_coo and Vector.from_coo infer the shape from the largest index when nrows/ncols/size are omitted, so trailing all-empty rows, columns, or positions are silently dropped. Add a warning to both docstrings pointing at the explicit nrows/ncols/size fix. Also a note on the module-level backend global that reading gb.backend does not trigger initialization: it is a plain global, not a special attribute, so it stays None on a fresh import until a special-attribute access or init() runs.
Add a user-guide subsection for plus_first and plus_second. They sum one operand's values while ignoring the other's, so when one operand is a boolean or iso adjacency they skip a plus_times multiply that would only multiply by one or rescale every term by the same constant. On a 0/1 matrix plus_first counts length-two paths. Includes a runnable example and lists both among the common semirings.
Document six public symbols absent from the API reference: IndexBinaryOp and Aggregator (operators), viz.spy and viz.datashade (visualization), and graphblas.init and graphblas.Recorder in a new utilities page wired into the reference toctree. The io converters and the collection classes' methods were already covered by existing autoclass :members: entries.
The Aggregator class had no docstring, so its API reference entry rendered with no description. Add a numpydoc class docstring in the style of the sibling operator classes: what an aggregator is (a reduction operator for reduce, reduce_rowwise, reduce_columnwise, reduce_scalar), the graphblas.agg namespace, the summary-versus-position split, and the note that an aggregator is composed from a monoid or semiring plus an optional finalize step per dtype rather than being a single GraphBLAS object. The position aggregators are named as agg.ss.argmin and friends. The bare agg.argmin spellings still resolve but raise DeprecationWarning pointing at agg.ss, so a new docstring should not teach them. Docstring-only, no code change.
The README's "Creating new Vectors / Matrices" block showed Matrix.new(dtype, num_rows, num_cols). There is no Matrix.new; the constructor is Matrix(dtype, num_rows, num_cols). Vector.apply built its error message from two adjacent string literals with no space at the join, so an invalid op reported "... `right` scalaror IndexUnaryOp with `right` thunk."
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.
Six documentation commits; no code changes apart from one error-message
string fix.
(bc1e467): the published snippet raised NameError (Vector was never
imported); the new page surfaces DataType's JIT introspection properties
and the dtypes registration helpers.
(a9c571a): trailing all-empty rows/columns/positions are silently
dropped when nrows/ncols/size are omitted; both docstrings now warn and
point at the explicit fix. Also a note that reading gb.backend does not
trigger initialization.
user-guide subsection with a runnable example (GH [doc] Add
plus_firstandplus_secondsemirings to docs #497).Aggregator, viz.spy, viz.datashade, graphblas.init, and Recorder
(GH [pyos][docs] API Docs missing large amount of user-facing functions/methods/classes #410, Table of contents for class methods #541).
entry previously rendered with no description.
(93bf5f7): there is no Matrix.new constructor, and Vector.apply's error
read "scalaror" from two joined string literals.
Stack created with GitHub Stacks CLI • Give Feedback 💬