Hi, thanks for taking the time to make this pull request. However, while I agree that this project needs better documentation, I don't think that these changes are the right way to do it, and hence I won't be merging them into my repository. Specifically, I see two issues:
1) In my experience of maintaining other open source repositories, having a partial documentation is worse than having no documentation (other than the doc strings), as users tend to make assumptions to fill the gaps rather read the code. If they are already reading the code doc strings, they are more likely to fill any remaining gaps by also reading the code.
2) Having another source of documentation other than the doc strings puts additional burdens on maintenance as now any changes in function definitions have to documented in two places rather than just one.
Personally, I like to use Sphinx in my projects to build external documentation from the function and class doc strings and then I host those on ReadTheDocs. For example, for my library netgraph the documentation can be found here. If you would like to collaborate on creating a proper documentation for this library, do let me know and then we can draw up a roadmap.
Hi, thanks for taking the time to make this pull request. However, while I agree that this project needs better documentation, I don't think that these changes are the right way to do it, and hence I won't be merging them into my repository. Specifically, I see two issues:
1) In my experience of maintaining other open source repositories, having a partial documentation is worse than having no documentation (other than the doc strings), as users tend to make assumptions to fill the gaps rather read the code. If they are already reading the code doc strings, they are more likely to fill any remaining gaps by also reading the code. 2) Having another source of documentation other than the doc strings puts additional burdens on maintenance as now any changes in function definitions have to documented in two places rather than just one.
Personally, I like to use Sphinx in my projects to build external documentation from the function and class doc strings and then I host those on ReadTheDocs. For example, for my library netgraph the documentation can be found here. If you would like to collaborate on creating a proper documentation for this library, do let me know and then we can draw up a roadmap.