Refactoring and enhancing user-facing Backend and Configs docs
#7404
Conversation
There was a problem hiding this comment.
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.
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 !
| 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.
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.
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.
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.
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.
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.
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.
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) | ||
|
|
Backend and Configsdocs(in cont. with [DOC, DISPATCH] : updated and addedbackend.py's docs #7305)Thank you :)