[pyos][question] Docs <-> code structure?

[sneakers-the-rat]

I'm reading through the user guide and trying to match the descriptions to implementations as I go, and I wonder how y'all are imagining this relatively slippery question of "User to developer experience"? Put another way -- what are your goals for having someone who is just using the package to be able to read the source and contribute to it? I think "we don't" is a fair answer, as it's by far the most common way software is structured, but just wanted to check.

Concretely, As I'm reading, I'm on the "fundamentals" page looking at the behavior of the overridden lshift operator ( https://python-graphblas.readthedocs.io/en/stable/user_guide/fundamentals.html#update-notation ) and trying to figure out where that's implemented in the code. I just did a ctrl+f for def __lshift__, but is the goal for the aspiring-developer-user to be able to back their understanding up into the code?

I feel like i'm not being clear here, so maybe another way of asking this question is how should someone go from reading the docs to reading the code? When I open the graphblas directory, how am I intended to understand what the submodules are doing? Since the API docs are not isomorphic with the project structure (which is fine) this is sort of challenging - there isn't a corresponding page in the docs that would tell me how the graphblas.core.base module works, for example.

If the goal is to make it easy for people to understand implementation (again, fine if that's not a primary goal) then i would def recommend having some additional description of how the package is organized. That would probably be best done in docstrings in the modules themselves, and then using automodule rather than writing a whole ton of narrative docs separate from the code, but i'm ultimately agnostic about the implementation.

edit: part of https://github.com/pyOpenSci/software-submission/issues/81

[eriknw]

Thanks for the discussion. I know (and you know) we need to improve documentation, so I think specific discussions/questions/suggestions like this are very helpful.

I think it would be too dense and confusing to try to have user documentation and developer documentation be intermixed (but, in an ideal world, it's probably fine for them to reference each other). Hence, the primary goal of "getting started", "user guide", and "API reference" is for users. I think it's useful to have developer documentation too.

And, yeah, I agree it's probably best to (at least begin with) more complete module docstrings and use automodule. I think we could also come up with a few koans or exercises to help guide new contributors solve tasks of increasing complexity hands-on. I don't think it would take many of these koans/exercises to illustrate the majority of likely new development, and they should be designed so people new to the codebase shouldn't get overwhelmed.

fwiw, I did work on some documentation this weekend: https://github.com/python-graphblas/python-graphblas/wiki . This is maintainer documentation aimed at making sure the project, uh, doesn't die and can be "maintained" (i.e., kept up to date with no new features) now and into the future. As I add these docs, I'm going to try to have our team take turns on different maintenance activities to increase our bus factor.

[sneakers-the-rat]

oh awesome! I didn't know the wiki was there. That would def be something that would be useful to link to from the docs (if it is already i hadn't seen it (the contributor guide section seems like the right place)