-
-
Notifications
You must be signed in to change notification settings - Fork 3.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Refactoring and enhancing user-facing Backend and Configs
docs
#7404
base: main
Are you sure you want to change the base?
Refactoring and enhancing user-facing Backend and Configs
docs
#7404
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for this!
I like the brief descriptions of the backends and all the wording checks.
The reorg is harder for me to visualize by looking at the diff. So I have to view the full source and/or the html docs. They seem good too.
See more minor comments below.
Co-authored-by: Dan Schult <dschult@colgate.edu>
Co-authored-by: Dan Schult <dschult@colgate.edu>
Co-authored-by: Dan Schult <dschult@colgate.edu>
Co-authored-by: Dan Schult <dschult@colgate.edu>
Co-authored-by: Dan Schult <dschult@colgate.edu>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this is ready to be merged. I don't see any specific questions yet to be resolved, and we can update the docs further in another PR.
Thanks @Schefflera-Arboricola !
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for these changes! This reads better. I left a few comments, and many of them remark on possible future enhancements.
that is similar to ``can_run``, but answers whether the backend *should* be run | ||
(converting if necessary). Like ``can_run``, it receives the original arguments |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I know you moved these lines from elsewhere, but I'm not sure this sentence is fully accurate or clear. should_run
is only run when doing conversions. Hence, should_convert_and_run
would be a more accurate name. @rlratzel and I have argued about this a couple times, b/c we sometimes get confused.
Perhaps an enhancement to should_run
could be to add e.g. requires_conversion=True
keyword to make this more clear and more useful.
4. ``on_start_tests`` (Optional): | ||
A special ``on_start_tests(items)`` function may be defined by the backend. | ||
It will be called with the list of NetworkX tests discovered. Each item | ||
is a test object that can be marked as xfail if the backend does not support | ||
the test using ``item.add_marker(pytest.mark.xfail(reason=...))``. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As a future enhancement, I think it would be nice to have a place that demonstrates how to use this effectively. For example, both cugraph and graphblas backends define something like this for convenience. Perhaps a more complete example could be in the backend cookie-cutter that we'd like to make from the j4f
or nx-loopback backends, and then this document could link there.
|
||
This decorator function dispatches to | ||
a different backend implementation based on the input graph types, and it also | ||
manages all the ``backend_kwargs``. Usage can be any of the following decorator |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this the first place we mention backend_kwargs
? How should we talk about backend functions allowing additional keyword arguments? For that matter, do we talk about what get_info
is able to return including "additional_docs"
?
Also, should we mention backend="my_backend"
to choose a bakcend when calling a dispatchable function?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It is previously mentioned on the "Backends and Config" docs page but this is the first time mentioned on the dispatchable
decorator docs page. On the "Backends and Config" docs page, I've made its explanation more detailed. Please look at it and LMK if something doesn't seem right there because I just tried to explain it by looking at the code in __call__
of the dispatchable
class, so I might be missing some context there. pls LMK if that looks fine.
I've also added the details of the get_info function as well.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
doc/reference/backends.rst
Outdated
@@ -2,18 +2,21 @@ | |||
Backends and Configs | |||
******************** | |||
|
|||
.. note:: Both NetworkX backend and config systems are experimental. They | |||
.. note:: Both NetworkX backend and config systems are experimental. Backends |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the original intent of the experimental status was more for backend developers than end users, meaning internal APIs used by backends may change, but the user-facing graph algos/functions are stable. Perhaps this entire sentence is dropped? If not dropped, can we reword it so users know the user-facing APIs (which is just the NX API itself) is stable?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I hope the updated note and the differentiation of "docs for users" and "docs for backend developer" resolve this comment.
And you can disable all the loggers by running this:: | ||
logging.disable(logging.CRITICAL) | ||
And then re-enable it by running:: | ||
logging.disable(logging.NOTSET) | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Backend and Configs
docs(in cont. with [DOC, DISPATCH] : updated and addedbackend.py
's docs #7305)Thank you :)