Doc organize Users Guide #24987
Doc organize Users Guide #24987
Conversation
Is there any way these divisions could be more descriptive/signposty? Like I think for important concepts, you're taking the divio approach of background, but I think it'd be helpful both for folks reading and writing docs to know why something is sorted in a specific category. |
|
Suggestions for more sign-posty are welcome. "Important concepts" is meant to be things you should understand to make the most use of the library, but don't necessarily impact day-to-day use once you understand them. For instance, knowing what a backend is is useful, and maybe if things go wrong you need to re-read this, but in general you don't need to read this once you have a backend set up. "Advanced topics" is things most users don't need to worry about unless you are doing something specialized. |
c4c7b48 to
b182628
Compare
| Animating plots <../../tutorials/introductory/animation_tutorial.rst> | ||
| Matplotlib toolkits (mplot3d, axes_grid1, axisartist) <../../tutorials/toolkits/index.rst> | ||
|
|
||
| Important concepts |
There was a problem hiding this comment.
| Important concepts | |
| Understanding how Matplotlib Works |
Or instead of works, is architectured/designed - like if we're gonna use long titles, may as well use them for scoping?
There was a problem hiding this comment.
I completely agree that this section should eventually live up to "Understanding how Matplotlib works"!
However, "Understanding how Matplotlib works" promises that, if a reader reads this, they will understand how Matplotlib works. I don't think the notes and tutorials referenced here quite meet up to that expectation. Hence the somewhat more general title. I guess we could do something like "Towards understanding how Matplotlib works" but thats quite a mouthful.
There was a problem hiding this comment.
I hear you, mostly I'm trying to pin down the distinction between this section and advanced, and riffing off my fave taxonomy of visualization libraries (https://m.youtube.com/watch?v=_H8y6j42Q2w), I think the division is
- using mpl building blocks to make viz
- what are the mpl building blocks
- how to build custom blocks
| Using Matplotlib | ||
| ################ | ||
|
|
||
| Creating and interacting with visualizations |
There was a problem hiding this comment.
I think it's OK to just have Creating/Making visualizations here
| ../../gallery/images_contours_and_fields/image_antialiasing.rst | ||
|
|
||
|
|
||
| Advanced topics |
There was a problem hiding this comment.
So I think these are for the most part these tutorials are about "optimizing and extending" library functionality, if we wanna work that into a title or blurb?
There was a problem hiding this comment.
Sure, we could use "Extending and optimizing Matplotlib" if thats all that we think will go in here.
|
As per the dev call, this sort of re-org will not work because the tutorial TOC is messed up. Instead we will want to move the tutorials to the appropriate place. That will take a change in sphinx-gallery sphinx-gallery/sphinx-gallery#1071, but should be possible. I'll put this as draft as not feasible in tis current form, though I think the proposed re-org of the subdirectories is reasonable start. |
|
sphinx-gallery/sphinx-gallery#1071 is in, so we should be able to use rst and python mixed into the same directories based on sphinx-gallery:master. That will really help us break free from organizing the docs based on whether they are galleries or not. Note one (current) limitation with SG is that it only does one sub level, so we could have Also the way we build our docs, if we make |
PR Summary
This is a relatively large change to the index of
users/explain. The table of contents has been organized intoLinked topics under each of these are from both the local rst files and liberally from the tutorials and the galleries. Linking to gallery items is actually pretty seamless, and the section navigation in the left sidebar keeps the top level nav rather than jumping into the gallery Nav, so I think it keeps viewers in the flow of reading the docs with this organization.
I've not added any new content, nor have I changed any tutorials etc to fit better in this organization.
There are infinite ways to organize this. If basic subsections are OK, I'd appreciate if reviews on exactly what I put where were kept to a minimum, we get this in, and then folks can refine with follow ups. Similarly if something was missed, or if there are glaring holes in the TOC as a users guide (for instance, I note that we seem to not have narrative docs on how to save a figure!) we can follow up. I don't expect this to get in for 3.7, for instance.
PR Checklist
Documentation and Tests
pytestpasses)Release Notes
.. versionadded::directive in the docstring and documented indoc/users/next_whats_new/.. versionchanged::directive in the docstring and documented indoc/api/next_api_changes/next_whats_new/README.rstornext_api_changes/README.rst