Reorganising documentation into Getting Started, Tutorial and How To #2778
Conversation
|
Just going to post the pic so we can see what it looks like along the side in the actual build. |
|
@JoeZiminski suggested putting the Viewers/Visualising_data section in the Tutorials. Thoughts? |
|
They aren't super informative (I mean depth-wise), so I would probably think of them more like "how to". Ie how to visualize your data rather than an in-depth visualization tutorial. As an aside: For me |
|
Agree @zm711 'Visualising Data' makes sense in 'How To...'. (maybe renamed to 'Visualise Data'). |
|
OK, I gave it some thought to this today. I would even vote to merge as it is and then we can discuss after as the rest. Another option is to make a PR where that is the only change. What do you think? That said, my opinion as I have read the documentation here and checked how some standard packages (numpy, scipy, scikit-learn, etc) handle their docs:
I think that big limitation that we have is the organization the documentation that reflects the package organization (the modules). This is easy for us programmers and a good start but overall I don't think it is a good organization principle. Users care about objects and we should center around those objects and what they make affordable. There are modules that maybe we don't want to document, and we don't need to explain everything about a module. |
|
EDIT: This post was a (longer than anticipated) post on 'Modules Documentation' which is now moved to #2800. |
There was a problem hiding this comment.
Hey @chrishalcrow this looks great, just a few small suggestions. I agree with @h-mayorquin this could be merged pretty much as-is.
doc/get_started/index.rst
Outdated
|
|
||
| installation | ||
| import | ||
| get_started |
There was a problem hiding this comment.
Would it make sense to change the order to:
- installation
- get_started
- import
- install_sorters
(just because new user is probably going to want to get an overview on getting started rather than dive into details on the imports).
Could 'How to "get started"' be renamed, maybe to 'Getting Started Tutorial'?
There was a problem hiding this comment.
actually @h-mayorquin 'quickstart' is good and avoids the redundancy between section name and tutorial name. Maybe 'Quickstart Guide' or 'Quickside Tutorial' just because 'quickstart' on it's own might be slightly amiguous?
doc/get_started/install_sorters.rst
Outdated
| @@ -0,0 +1,338 @@ | |||
| .. _installsorters: | |||
There was a problem hiding this comment.
I wonder if this page can also be moved, maybe to what is currently 'In-Depth'? As the use of docker images is recommended in the article this is less general-use than originally anticipated.
There was a problem hiding this comment.
On further consideration I don't think now is the time to do it, and it wouldn't really go with the rest of 'In Depth', so makes sense to ignore this for now.
doc/get_started/import.rst
Outdated
| @@ -0,0 +1,81 @@ | |||
| Importing SpikeInterface | |||
There was a problem hiding this comment.
As a general point I think the 'Importing SpikeInterface' page is confusing for new users and should probably go under developer docs. Maybe it is a good time to finalise the discussion from #2046. It is useful to have a place to discuss the different ways of importing but I don't think new users should be concerned with it. They should be recommended a way to a) reduce mental load b) ensure a consistency in how the package is used across the community.
For example SciPy have a discussion on importing in their API docs but in the User Guide they just introduce a consistent way from the start and don't discuss.
There was a problem hiding this comment.
That discussion will never be solved haha so this doc was the compromise :)
There was a problem hiding this comment.
Haha yes I had forgotton the extent of the discussion 😄 Okay makes sense
|
My vote would be these 3 changes and then do a better cleanup either 1) after the conference or 2) hackathon
|
|
Agree with @h-mayorquin and @zm711 my only thought is 'Visualising Data' could go in 'How To' rather than 'Getting Started' as I think unless you are familiar with SI the article will not make much sense. |
|
@JoeZiminski you want to post your big comment somewhere else? Maybe one of the document issues. I think it has a lot of wonderful food for thought for the next phase of doc edits and I don't want to lose it when this merged. |
|
Sure thanks @zm711, do you think a new issue would make sense?
|
|
I think a new issue would be fine. We can have a fresh start! |
|
Thinking twice I don't think we should merge this yet. I think we should remove the generated files out of version control. |
|
Lots of discussion, great! I'll implement the generally agreed about stuff later, then need to check the version control stuff (good catch @h-mayorquin), and try to clean up references to the old Section names throughout the docs. And we'll talk about what goes where and what can be split-up etc in person in Edinburgh? Talking of names, seems like "Module documentation" still wins. Let's keep it for now? @alejoe91 suggested "Module by Module" as a name for "Module documentation". I thought it sounded terrible at first, but woke up thinking it was a nice name.
Agreed. I wanted to include this as it shows the stylistic constraints if we use sphinx-gallery: we can include basic rst files, but the way they're included means it's not easy to bundle them with the gallery tutorials. So their either in their own section (here in the "Tutorials without a notebook" section) or could be in a subsection, but would appear as a list of links instead of a gallery card. But you're right, for these examples are there are easy fixes: have neuropxiles as a how-to and put "WE to SA" in its own section. |
|
Sounds good @chrishalcrow! Happy to keep 'Module Documentation' for now. In general my thoughts are to keep the documentation as accessible as possible, as many users may not be very experienced with python. Imagining yourself as a new user with limited python experience navigating the website for the first time, anything with 'Module' in the name is not informative. Obviously the docs will need to get technical in places but not on the front page. So I would advocate for changing it later but happy to keep as is as there are many changes and discussions to come. In terms of the timeline, for me personally I am away next week but then back on ephys stuff now hopefully for a long while and was planning to help with the documentation as I realised I've never read it all the way through. So for me it would work to continue discussion and refactorings up until the conference, and this may leave only the bigger things to tackle in person. But happy to proceed in whatever way works best for everyone! |
|
Wait! I've done a stupid thing with the analyze neuropixles how to... DON'T MERGE |
|
Thanks Chris! I kind of ignored
|
|
BTW the title of this PR could be renamed before merge now that the structure is more decided. How about 'Reorganising documentation into Getting Started, Tutorial and How To.'? |
I think these could all be regressions! We will need to double check them carefully! |
for more information, see https://pre-commit.ci
for more information, see https://pre-commit.ci
|
Hello. Yes, I must have messed something up early. It was hard to spot because I had also messed up the gitignore so it was hard to work through the diffs. I know that I didn't properly rerun the quickstart tutorial properly. Now this PR is only 24 lines extra, which sounds very reasonable. Once it's finished running, could people have a final check? @h-mayorquin @zm711 @JoeZiminski |
chrishalcrow
changed the title
There was a problem hiding this comment.
This png are generated files. I think we should remove them from version control, right?
There was a problem hiding this comment.
No they are used in the rst, so they need to be there
There was a problem hiding this comment.
But they are generated on the read the docs so they will be there for the rst to display. They just don't need to be in version control. Am I wrong?
There was a problem hiding this comment.
These are generated in a different way than the sphinx-gallery files. They're run locally so that we can do big computations and use larger data files. See here: https://github.com/SpikeInterface/spikeinterface/tree/main/examples/how_to
To be honest, they are a pain, but that's a discussion for another PR!
There was a problem hiding this comment.
OK, thanks for the pointer. I forgot that there is yet-another-system of generating files in the docs. Maybe the simplest if to just not change the images every time we run the code (they should be the same!). We should discuss this in another PR or issue though as this is creating the dreaded super large repo of @samuelgarcia .
|
I checked generated docs and they look OK to me Let's not forget to squash the commit history for this one! I don't like "Modules Documentation" because I don't want to structure the documentation around modules. I want to add in depth sections about the |
|
@h-mayorquin, Joe just opened a new issue to discuss a deeper rearrange once this toctree is done. You should read his takes and then add your own there! #2800. |
|
Just two typos and then this looks good to me (one comment that doesn't necessarily need to be addressed here). |
|
This is good for me. Anything else you wanted @h-mayorquin ? |
|
Thanks for the push for this @chrishalcrow |
|
Thanks for getting this merged - I've been on holiday (I maybe should have mentioned that at some point!!) Looking forward to much more documentation discussion in the next couple of months! |
New documentation structure, based on discussions in #2763 and #2327.
The reorganised docs:
https://spikeinterface--2778.org.readthedocs.build/en/2778/
Idea is to make the documentation simpler to navigate for new (to si and to coding) users. Main toctree is
I deliberately just changed the structure and moved files around, and didn't change the files themselves (except some titles, and descriptions on index pages). Once this overall structure is fixed, we can have other debates about what belongs where, and what is missing.
The tutorials are generated by sphinx-gallery, but contain some "plain" rst files. This works, but the two types are linked from index in two different ways. I think this is fine.
The build looks fine locally, but I'm sure there will be some broken things.
Not sure about the name "In-depth". I quite like "How to...". Opinions welcome on everything!
@h-mayorquin @zm711 @JoeZiminski @alejoe91 @samuelgarcia