- Notifications
You must be signed in to change notification settings - Fork15
Description
As-is, only the top-level classes are included in the API documentation, which seems to leave out most of the user-facing functions if i'm not mistaken?
Eg. I was trying to figure out how I would know about the various classes/functions used in the example notebooks, like i sawbinary.truediv in the pagerank example, and there is nothing like that in the API docs.
It seems like the place these are documented are here (for operators):https://python-graphblas.readthedocs.io/en/stable/user_guide/operators.html but that list is hardcoded and so misses a decent amount of the available binary operators (table at bottom of issue).
Ideally these would all be listed in the API docs, which I think would require a refactor of the docs (#409 ).
Since this package is a wrapper of a few different packages, it doesn't seem practical or useful to document every single one of these functions/classes, since presumably the wrapped libraries have their own documentation. It should be possible to list them and link to the original docs, however, and that seems like a pretty necessary thing to have in place to make this broadly usable by people who don't already know GraphBLAS from other contexts (I'm assuming these are all standard across GraphBLAS distributions?).
Aside from the wrapped functions/classes, there are a large number of functions/classes that lack a docstring (351 by an inspection that also includes trivially missing docstrings like module-level docstrings. You all will have a better sense of what counts as "user-facing" in this context, but presumably some subset of those are intended for use by the user.
From a developer/contributor POV, this additional documentation would be necessary for me to contribute to the package, as currently I am trying to make sense of the structure of the package, and some narrative docs in, for example, the positively massivecore/operator.py file would go a long way in helping me understand that. Again, understanding this is a wrapper package which requires a lot of metaprogramming, so some documentation concerns don't apply since the functions/methods are generated dynamically, but as is I don't see a way for me to understand how that metaprogramming works. Perhaps that should be a separate issue though.
dir(graphblas.binary) | docs |
|---|---|
| 'absfirst' | |
| 'abssecond' | |
| 'any' | |
| 'atan2' | 'atan2' |
| 'band' | 'band' |
| 'bclr' | |
| 'bget' | |
| 'binom' | |
| 'bor' | 'bor' |
| 'bset' | |
| 'bshift' | |
| 'bxnor' | 'bxnor' |
| 'bxor' | 'bxor' |
| 'cdiv' | |
| 'cmplx' | |
| 'copysign' | |
| 'eq' | 'eq' |
| 'first' | 'first' |
| 'firsti' | |
| 'firsti1' | |
| 'firstj' | |
| 'firstj1' | |
| 'floordiv' | |
| 'fmod' | 'fmod' |
| 'from_string' | |
| 'ge' | 'ge' |
| 'gt' | 'gt' |
| 'hypot' | |
| 'isclose' | |
| 'iseq' | |
| 'isge' | |
| 'isgt' | |
| 'isle' | |
| 'islt' | |
| 'isne' | |
| 'land' | 'land' |
| 'ldexp' | |
| 'le' | 'le' |
| 'lor' | 'lor' |
| 'lt' | 'lt' |
| 'lxnor' | 'lxnor' |
| 'lxor' | 'lxor' |
| 'max' | 'max' |
| 'min' | 'min' |
| 'minus' | 'minus' |
| 'ne' | 'ne' |
| 'numpy' | |
| 'pair' | 'pair' |
| 'plus' | 'plus' |
| 'pow' | 'pow' |
| 'rdiv' | |
| 'register_anonymous' | |
| 'register_new' | |
| 'remainder' | |
| 'rfloordiv' | |
| 'rminus' | |
| 'rpow' | |
| 'rtruediv' | |
| 'second' | 'second' |
| 'secondi' | |
| 'secondi1' | |
| 'secondj' | |
| 'secondj1' | |
| 'ss' | |
| 'times' | 'times' |
| 'truediv' | 'truediv' |
Related to:#409
Part of:pyOpenSci/software-submission#81