Refactor the documentation into more dedicated tutorials #237
Conversation
Don't include them in the README since it's a bit useless there.
Will split it up into managing a data collection and using pooch in a package
We don't want people thinking that they have to do it.
leouieda
changed the title
|
This is ready for review. Any feedback is welcome but I particularly like to hear from users who aren't super familiar with the project (@mycarta I remember you had some questions about Pooch a while back). You can see the rendered docs here: https://www.leouieda.com/docs-previews/pooch/237/ |
There was a problem hiding this comment.
Looks good to me! Although I think my opinion might be biased due to my knowledge on Pooch. @prisae asked a few questions on Slack regarding the application of Pooch to one of his projects, maybe he can make a better review.
There was a problem hiding this comment.
LGTM
Mind you - I have very limited knowledge of pooch, I just started to use it in a few examples of the emg3d-gallery two weeks ago or so, I only scratched the surface. I plan to use it more in the future though.
However, I only looked from the theme-change angle, as I think this is the purpose of this PR; if there should be content changes they would probably better live in a new PR afterwards, to keep this one with the theme...!?
One thing though: Did you plan to move from master->main? - If so, it might be a good point when changing the theme, as you will have to update potentially various links in the docs too.
|
@santisoler @prisae thanks for the reviews! @prisae the theme change was actually done in #236 without touching the content of the docs. This one is actually about reorganizing the content. My main motivation was that I could never remember which of the tutorial pages (beginner, intermediate, advanced, downloaders, processors) had the information I was after. So I wanted to break things up into separate pages to make them easier to find in the menu. As a new user, your perspective on this would be appreciated. For example, is it easier to find information in the new layout than in https://www.fatiando.org/pooch/dev/ (same theme, different layout)? |
|
Having a side-by-side comparison I think it is about equal. The main "chapters" are probably better visible in the current docs due to the blue titles on a black background (but that is theme related and nothing I would change). I tried (https://emg3d.emsig.xyz) to follow pandas (and new also SciPy's) style of start page - I do think it can help to guide the user, instead of having straight off a lot of text on the first page. https://pandas.pydata.org/docs/ But then again, it is probably personal preference. It just can be overwhelmingly busy, the current startpage. |
|
Thanks @aguspesce @prisae! I see your point about the home page. I agree that it's too busy and we should have a clearer message about where to start reading the docs. Since everyone seems happy with the changes in this PR, I'll merge this in for now and then work on the front page in a follow up. |
The docs were organized by level (beginner to advanced), which is good if reading it from start to finish. But that format is not great when going back to try to find out how to do something. Here, I break apart the larger pages into separate tutorials based on topic. The beginner tutorial is moved to "Getting started" and split into "Fetching multiple files" and "Managing a package's data". Also specify the API pages as "List of functions and classes (API)" since novices are likely not used to the term API.
This is a preview of the built documentation: https://www.leouieda.com/docs-previews/pooch/237/
Reminders:
make formatandmake checkto make sure the code follows the style guide.doc/api/index.rstand the base__init__.pyfile for the package.AUTHORS.mdfile (if you haven't already) in case you'd like to be listed as an author on the Zenodo archive of the next release.