Final documentation improvements #8555
Comments
|
|
A. don't know if data kwarg needs full blown tutorial, wonder if a simple example will do the trick. - Yes, I keep harping on this 'cause I think a lot of the examples lean towards showing all the things and so it can get hard to figure out how to do the 1 thing. |
|
Totally agree w/ it not needing its own tutorial, maybe just a section of a tutorial that's updated to show off this usecase plus the quick example. I think an example is actually a better place to convey this info, but the examples page is so long that it's really hard to parse :-/ |
|
Yeah, I think an upcoming documentation issue should be "gutting examples" ... Also, is there a way we can invite the people who critique the docs (and write long blog posts critiquing the docs) to give us feedback on the refactor? We should at least solicit some feedback from users who aren't us... |
|
yeah - I think that prioritizing the most useful / helpful / well-constructed examples at the top is a good start! |
|
btw - I reached out to the author of that post on reddit, and he said he's more than happy (I believe he said he'd be honored actually ;-) ) to have us cannibalize some of his content for a tutorial |
|
I'm going to close this, as I think that the bulk of the work is done and there are PRs/Issues for the other stuff. |
Uh oh!
There was an error while loading. Please reload this page.
After many weeks of work I think that the documentation is in a much better state now. I think that we are 80% of the way towards considering this "good enough" for now. This issue is a place to keep some lingering issues / ideas that could be implemented before 2.1 is released:
ToDo
Cycler documentation
Use of the cycler should be demoed more extensively in the examples, and should also be introduced and explained in an introductory tutorial. See scipy2017 sprint - docs #8885
The developers guide should be updated and made more clear.outside the scope of this issue I thinkThis blog post or something like it should be converted into a "getting started with matplotlib" kind of thing. Maybe we should reach out to the author and ask them to submit it as a sphinx-gallery python file.
We need to go through all the open PRs that were working on sphinx gallery and make sure that they get either closed because the work has already been done, or merged soon otherwise they'll quickly become forgotten PRs.
In progress
datakwarg, show how it is used in a tutorial and show some examples that use it. Ideally using pandas dataframes (I know it adds a dependency but I guarantee that users want to know how to do this) (adding keyword plotting #8566)From @story645: I've been wanting a simple gallery of sorts that goes over the basic plot types - line, scatter, bar, pie, heatmap - in like 5 lines or less w/ nothing fancy and I think that'd be perfect for a tutorial type section.
This is quite similar to the screenshots page, which is currently buried and kinda hard to find. IMO we should turn this into a
plot typesfolder in the tutorials section, and have one short example for each plot type. (linking front thumbnails, updating screenshots + pyplot API page #8581 for starters)I think this will go a long way towards bringing MPL's documentation into the 21st century.
As a general thought, any time somebody writes a blog post that makes an incorrect assumption about matplotlib, e.g. this one, we should take a hard look at the docs and figure out how to make that feature/ use-case easier to find. In addition, any time somebody writes a clear, well-written blog post that is better at explaining things than the MPL docs, we should improve the docs or ask that person to contribute their post as a tutorial.
Let me know if there are any other suggestions for this issue and I can append to the list. Is there any ETA on 2.1? I wanna make sure this is a realistic goal.
@story645 @NelleV @tacaswell @phobson @anntzer @dopplershift @QuLogic
The text was updated successfully, but these errors were encountered: