add function description #105
Conversation
There was a problem hiding this comment.
WOOOHOOO! 😻 You have done the thing closest to my heart, which is adding to a project's documentation as a new user! ✨ Unfortunately I'm going to reject a few of your changes 😭
The motivation of the "thresholding" section in the "creating a network" page in the documentation is to provide an overview of the meaning and purpose of thresholding the graph. Function descriptions are included in the source code using doc strings (more info on that here) (and also here) and do not need to be manually added into the documentation! (:heart: thank you sphinx).
If you like it might still be a good idea to add a link to the documentation for thresholding methods into this section. This can be done by adding :function:`scona.threshold_graph` and :function:`scona.BrainNetwork.threshold` to the rst. Sphinx (:heart:) will automatically render these as links to the appropriate documentation.
Reading your changes I get the impression you know a bit about network science or graph theory. If this impression is correct perhaps you would like to write a few lines of explanation of what it means to threshold a graph and what we mean by a "minimum spanning tree". That's what I really had in mind for that section of the page.
You have also caused me to realise (and this is why contribution from people who didn't write the code is so important 🎉) that the documentation is actually pretty hard to navigate. Of course you don't know that all the functions have docstrings rendered into docs by sphinx, since nowhere in the introduction do we link to these! This has now become its own issue #106
| @@ -19,10 +17,24 @@ This is a very lightweight subclass of the :class:`networkx.Graph` class. This m | |||
|
|
|||
| All :class:`scona.BrainNetwork` **methods** have a corresponding ``scona`` **function**. So while the :class:`scona.BrainNetwork` methods can only be applied to :class:`scona.BrainNetwork` objects, you can find the equivalent function in ``scona`` which can be used on a regular :class:`networkx.Graph` object. | |||
|
|
|||
| For example, if ``G`` is a :class:`scona.BrainNetwork` object, you can threshold it by typing ``G.threshold(10)``. If ``nxG`` is a :class:`Networkx.Graph` you can use ``scona.threshold_graph(nxG, 10)`` to perform the same function. | |||
There was a problem hiding this comment.
I would like to leave this line where it is to illustrate the line above. This example is more about showing that class methods and functions come in pairs, rather than explaining the threshold function.
I'm ready to merge
What's the context for this pull request?
(this is a good place to reference any issues that this PR addresses)
I wrote a few lines to documentation
What's new?
Added description for Threshold function
What should a reviewer feedback on?