Re: [matplotlib-devel] matplotlib user guide
For the record, I've spoken to Mark about this face-to-face in the past, and I think he has some great ideas about how the user guide should look. Personally I would agree that the user guide is currently not targeted enough (it takes 3 pages full of text before getting to a simple plt.plot() ) and even then, I don't think it is sympathetic enough to really new users. Clearly matplotlib's success shows that the documentation must be doing something right, but I think the user guide could definitely be improved. Mark, from what I remember your changes were along the lines of moving sections around, and splitting some sections into beginner & advanced pages. I think detailing a few examples of the types of changes you have in mind might help us to have a bit more clarity on what you are proposing. Thanks for getting involved in improving the docs! On 25 September 2013 09:19, mark wrote: > hi matplotlib developers > > I have been considering the matplotlib user guide structure and it > has occured to me that there are two user guides interleaved here: > 1. Introduction for new users > 2. Library tour for developers > > I think that this structure makes it challenging for new users to > benefit from the user guide as much as they could. > > I would like to see the user guide separated into two sections, with > the two different audiences in mind. I feel this would enable new > users of the library to have a more targeted introduction to some of > the neat features without getting bogged down in details they are > unlikely to need (or comprehend). > > I am very happy to have a go at this and put up a set of suggested > changes but I would value input from the community on this approach and > my category suggestions before I submit a pull request. > > many thanks > mark > > > > -- > October Webinars: Code for Performance > Free Intel webinars can help you accelerate application performance. > Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most > from > the latest Intel processors and coprocessors. See abstracts and register > > http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk > ___ > Matplotlib-devel mailing list > Matplotlib-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/matplotlib-devel > -- October Webinars: Code for Performance Free Intel webinars can help you accelerate application performance. Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from the latest Intel processors and coprocessors. See abstracts and register > http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] matplotlib user guide
Thanks for the interest. I agree there's lots that can be done to improve it. You may want to familiarize yourself with MEP10 ( https://github.com/matplotlib/matplotlib/wiki/Mep10) though that mainly deals with docstrings and not the narrative documentation. Perhaps as a starting point, you'd want to write a MEP with your specific proposals -- maybe as a set of guidelines for how the docs should be laid out (with a few concrete examples of such changes, but without going through the laborious process of making all such changes). The nice thing about writing a MEP is that then we can point other people who want to help out to it and say "this is what we're trying to do", rather than the burden of all of the work being on just a single person. At least that's the idea ;) Mike On 09/25/2013 04:19 AM, mark wrote: hi matplotlib developers I have been considering the matplotlib user guide structure and it has occured to me that there are two user guides interleaved here: 1. Introduction for new users 2. Library tour for developers I think that this structure makes it challenging for new users to benefit from the user guide as much as they could. I would like to see the user guide separated into two sections, with the two different audiences in mind. I feel this would enable new users of the library to have a more targeted introduction to some of the neat features without getting bogged down in details they are unlikely to need (or comprehend). I am very happy to have a go at this and put up a set of suggested changes but I would value input from the community on this approach and my category suggestions before I submit a pull request. many thanks mark -- October Webinars: Code for Performance Free Intel webinars can help you accelerate application performance. Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from the latest Intel processors and coprocessors. See abstracts and register > http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel -- _ |\/|o _|_ _. _ | | \.__ __|__|_|_ _ _ ._ _ | ||(_| |(_|(/_| |_/|(_)(/_|_ |_|_)(_)(_)| | | http://www.droettboom.com -- October Webinars: Code for Performance Free Intel webinars can help you accelerate application performance. Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from the latest Intel processors and coprocessors. See abstracts and register > http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] matplotlib user guide
On 2013/09/24 10:19 PM, mark wrote: > hi matplotlib developers > > I have been considering the matplotlib user guide structure and it > has occured to me that there are two user guides interleaved here: >1. Introduction for new users >2. Library tour for developers > > I think that this structure makes it challenging for new users to > benefit from the user guide as much as they could. > > I would like to see the user guide separated into two sections, with > the two different audiences in mind. I feel this would enable new > users of the library to have a more targeted introduction to some of > the neat features without getting bogged down in details they are > unlikely to need (or comprehend). > > I am very happy to have a go at this and put up a set of suggested > changes but I would value input from the community on this approach and > my category suggestions before I submit a pull request. Mark, There is no doubt that the documentation can be improved, both via changes in organization and wording, and by adding missing parts. I'm happy to see you work on this, and look forward to the next increment of detail regarding your strategy. Eric > > many thanks > mark > > > -- > October Webinars: Code for Performance > Free Intel webinars can help you accelerate application performance. > Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from > the latest Intel processors and coprocessors. See abstracts and register > > http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk > ___ > Matplotlib-devel mailing list > Matplotlib-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/matplotlib-devel > -- October Webinars: Code for Performance Free Intel webinars can help you accelerate application performance. Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from the latest Intel processors and coprocessors. See abstracts and register > http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] matplotlib user guide
Many thanks for the feedback. So ,my first cut was to segregate the user guide by topic. Below is the summary I had in mind for an Introduction for New Users. Hopefully this gives a flavour of what I have in mind. I will attempt to put this into practice and post again when I have a user guide coded that might work in my view. mark Introducing Plotting with Matplotlib Pyplot tutorial Controlling line properties Working with multiple figures and axes Working with text Interactive navigation Navigation Keyboard Shortcuts Working with text Text introduction Basic text commands Text properties and layout Writing mathematical expressions Text rendering With LaTeX Annotating text Image tutorial Startup commands Importing image data into Numpy arrays Plotting numpy arrays as images Customizing Location of Subplot Using GridSpec Basic Example of using subplot2grid GridSpec and SubplotSpec Adjust GridSpec layout GridSpec using SubplotSpec A Complex Nested GridSpec using SubplotSpec GridSpec with Varying Cell Sizes Legend guide What to be displayed Multicolumn Legend Legend location Multiple Legend Legend of Complex Plots Annotating Axes Annotating with Text with Box Annotating with Arrow Placing Artist at the anchored location of the Axes Using Complex Coordinate with Annotation Using ConnectorPatch Zoom effect between Axes Define Custom BoxStyle Our Favorite Recipes Sharing axis limits and views Easily creating subplots Fixing common date annoyances Fill Between and Alpha Transparent, fancy legends Placing text boxes -- October Webinars: Code for Performance Free Intel webinars can help you accelerate application performance. Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from the latest Intel processors and coprocessors. See abstracts and register > http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] matplotlib user guide
In article <20130927140906.3ded3...@metarelate.net>, mark wrote: > Many thanks for the feedback. > > So ,my first cut was to segregate the user guide by topic. Below is > the summary I had in mind for an Introduction for New Users. > > Hopefully this gives a flavour of what I have in mind. > > I will attempt to put this into practice and post again when I have a > user guide coded that might work in my view. > > mark > > > Introducing Plotting with Matplotlib > > Pyplot tutorial > Controlling line properties > Working with multiple figures and axes > Working with text > Interactive navigation > Navigation Keyboard Shortcuts > Working with text > Text introduction > Basic text commands > Text properties and layout > Writing mathematical expressions > Text rendering With LaTeX > Annotating text ... On the whole this looks good to me. I so have a few comments, however: - Would you be willing to include a section on using the class API? (I'm assuming the above is all based on using pyplot?). I find there is a huge gap between pyplot and the class API, and the documentation I've found does little to bridge that gap. - You have "Working with text" (including "annotating text") early on, then "Legend guide" and "Annotating Axes" much later on. I wish these were all together, as axes (values and labels), plot titles and legends are arguably the main use cases for text in plots. Perhaps it would suffice to have "Working with text" give a brief overview of how to do each of these things, with pointers to the other sections for details. An alternative is subsections within Working with text. - In a similar vein: I'm surprised GridSpec comes before legends and annotating axes. - Please consider a section on 3-d plots. - Please consider a section on animation. -- Russell -- October Webinars: Code for Performance Free Intel webinars can help you accelerate application performance. Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from the latest Intel processors and coprocessors. See abstracts and register > http://pubads.g.doubleclick.net/gampad/clk?id=60134791&iu=/4140/ostg.clktrk ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] matplotlib user guide
On Fri, Oct 4, 2013 at 1:40 PM, Russell E. Owen wrote: >> Introducing Plotting with Matplotlib >> >> Pyplot tutorial >> Controlling line properties >> Working with multiple figures and axes >> Working with text >> Interactive navigation >> Navigation Keyboard Shortcuts >> Working with text >> Text introduction >> Basic text commands >> Text properties and layout >> Writing mathematical expressions >> Text rendering With LaTeX >> Annotating text > ... > - Would you be willing to include a section on using the class API? (I'm > assuming the above is all based on using pyplot?). +inf Even better, dump pyplot and use primarily the OO API. Asside from folks that dont want to change anything when moving from Matlab, we should all be using teh primarily OO API. is it really that hard to type: ax.plot() rather than plot() ? And when you move away from interactive use (and we all should fi your typing more than 4-5 lines of code) teh OO interface is a much better way to go. (I know, iPython notebooks allow you do do a LOT with esentially an interactive interpreter, but still.) Anyway, I've always thought it was a real shame that most of the tutorials on MPL out there get people started on what I'm convinced is the wrong foot. - just my opinionated $0.02 worth... -Chris -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R(206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception chris.bar...@noaa.gov -- October Webinars: Code for Performance Free Intel webinars can help you accelerate application performance. Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from the latest Intel processors and coprocessors. See abstracts and register > http://pubads.g.doubleclick.net/gampad/clk?id=60135031&iu=/4140/ostg.clktrk ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] matplotlib user guide
On Fri, Oct 18, 2013 at 2:13 PM, Chris Barker wrote: > On Fri, Oct 4, 2013 at 1:40 PM, Russell E. Owen wrote: > >> Introducing Plotting with Matplotlib > >> > >> Pyplot tutorial > >> Controlling line properties > >> Working with multiple figures and axes > >> Working with text > >> Interactive navigation > >> Navigation Keyboard Shortcuts > >> Working with text > >> Text introduction > >> Basic text commands > >> Text properties and layout > >> Writing mathematical expressions > >> Text rendering With LaTeX > >> Annotating text > > ... > > > - Would you be willing to include a section on using the class API? (I'm > > assuming the above is all based on using pyplot?). > > +inf > > Even better, dump pyplot and use primarily the OO API. Asside from > folks that dont want to change anything when moving from Matlab, we > should all be using teh primarily OO API. > > is it really that hard to type: > > ax.plot() > > rather than > > plot() ? > > And when you move away from interactive use (and we all should fi your > typing more than 4-5 lines of code) teh OO interface is a much better > way to go. > > (I know, iPython notebooks allow you do do a LOT with esentially an > interactive interpreter, but still.) > > Anyway, I've always thought it was a real shame that most of the > tutorials on MPL out there get people started on what I'm convinced is > the wrong foot. > > - just my opinionated $0.02 worth... > > -Chris > > FWIW, I think my "Anatomy of Matplotlib" tutorial I gave at SciPy 2013 struck a balance between pyplot and the OO interface. I welcome any and all feedback on that tutorial which I plan to give again next year as well as an intermediate "Anatomy of Matplotlib" tutorial. Cheers! Ben Root -- October Webinars: Code for Performance Free Intel webinars can help you accelerate application performance. Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from the latest Intel processors and coprocessors. See abstracts and register > http://pubads.g.doubleclick.net/gampad/clk?id=60135031&iu=/4140/ostg.clktrk___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] matplotlib user guide
hi matplotlib developers as I previously posted, I have thought about structure and flow of the user guide my fist cut of a change set is viewable here: https://github.com/marqh/matplotlib/compare/userGuideShape it keeps all of the same content as the current user guide but subdivides some sections into categories: configuration beginner's guide advanced guide So, all feedback very gratefully received, but a particular focus requested on: - sub-section headings - sub-section contents (scope) - ordering I would like to focus on getting the categorisation and ordering helpful for this piece of work. I feel that this will give us more accessible ways into adding new sections or adapting sections but that this should wait for a follow up activity. many thanks mark On Wed, 25 Sep 2013 08:19:59 + mark wrote: > hi matplotlib developers > > I have been considering the matplotlib user guide structure and it > has occured to me that there are two user guides interleaved here: > 1. Introduction for new users > 2. Library tour for developers > > I think that this structure makes it challenging for new users to > benefit from the user guide as much as they could. > > I would like to see the user guide separated into two sections, with > the two different audiences in mind. I feel this would enable new > users of the library to have a more targeted introduction to some of > the neat features without getting bogged down in details they are > unlikely to need (or comprehend). > > I am very happy to have a go at this and put up a set of suggested > changes but I would value input from the community on this approach > and my category suggestions before I submit a pull request. > > many thanks > mark > > > -- > October Webinars: Code for Performance > Free Intel webinars can help you accelerate application performance. > Explore tips for MPI, OpenMP, advanced profiling, and more. Get the > most from the latest Intel processors and coprocessors. See abstracts > and register > > http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk > ___ Matplotlib-devel > mailing list Matplotlib-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/matplotlib-devel -- October Webinars: Code for Performance Free Intel webinars can help you accelerate application performance. Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from the latest Intel processors and coprocessors. See abstracts and register > http://pubads.g.doubleclick.net/gampad/clk?id=60135031&iu=/4140/ostg.clktrk ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] matplotlib user guide
On Fri, Oct 18, 2013 at 11:56 AM, Benjamin Root wrote: > FWIW, I think my "Anatomy of Matplotlib" tutorial I gave at SciPy 2013 > struck a balance between pyplot and the OO interface. Grat, I'll take a look. Does the ipynb linked from the tutorial site have most of the presentation material? As it turns out, I need to give an intro to matplotlib class this week -- I've been looking for some good materials to use -- why re-invent the wheel? I'll be sure to give you any feedback I have. Hmmm.. this may be a time to put together a project of materials designed to teach matplotlib in a classroom setting -- a little different than a tutorial designed to be done on one's own. There is a bunch of stuff scattered among scipy tutorials, bootcamp lectures, etc, but having a central place to develop materials would be nice. -Chris -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R(206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception chris.bar...@noaa.gov -- October Webinars: Code for Performance Free Intel webinars can help you accelerate application performance. Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from the latest Intel processors and coprocessors. See abstracts and register > http://pubads.g.doubleclick.net/gampad/clk?id=60135031&iu=/4140/ostg.clktrk ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] matplotlib user guide
On Mon, Oct 21, 2013 at 1:26 PM, Chris Barker wrote: > On Fri, Oct 18, 2013 at 11:56 AM, Benjamin Root wrote: > > > FWIW, I think my "Anatomy of Matplotlib" tutorial I gave at SciPy 2013 > > struck a balance between pyplot and the OO interface. > > Grat, I'll take a look. > > Does the ipynb linked from the tutorial site have most of the > presentation material? > > Yup. Most of it is in the notebook. Here is the repo: https://github.com/WeatherGod/AnatomyOfMatplotlib > As it turns out, I need to give an intro to matplotlib class this week > -- I've been looking for some good materials to use -- why re-invent > the wheel? > > I'll be sure to give you any feedback I have. > > Thanks! That would be appreciated! I am glad this will (hopefully) save time and effort on your part to get others ramped up. > Hmmm.. this may be a time to put together a project of materials > designed to teach matplotlib in a classroom setting -- a little > different than a tutorial designed to be done on one's own. > > There is a bunch of stuff scattered among scipy tutorials, bootcamp > lectures, etc, but having a central place to develop materials would > be nice. > > -Chris > > I agree with you in principle, but I think the question is "central to whom?" The bootcamps are useful for their own purposes and audiences, while the scipy tutorial s are useful for their own things, etc. At this point, I think the bootcamps and SciPy and other conferences really should be the best venues for pushing out the "classroom-oriented" type of tutorials. Cheers! Ben Root -- October Webinars: Code for Performance Free Intel webinars can help you accelerate application performance. Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from the latest Intel processors and coprocessors. See abstracts and register > http://pubads.g.doubleclick.net/gampad/clk?id=60135031&iu=/4140/ostg.clktrk___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
Re: [matplotlib-devel] matplotlib user guide
Thank you all for the thoughts so far I have raised a pull request: https://github.com/matplotlib/matplotlib/pull/2554 To be clear, this is a 'structure only' pull request, I have made no documentation changes as yet. I see this as a part of the process. If we can agree structure we can work on aspects of the user guide, adding content into appropriate sections. all the best mark On Wed, 25 Sep 2013 08:19:59 + mark wrote: > hi matplotlib developers > > I have been considering the matplotlib user guide structure and it > has occured to me that there are two user guides interleaved here: > 1. Introduction for new users > 2. Library tour for developers > > I think that this structure makes it challenging for new users to > benefit from the user guide as much as they could. > > I would like to see the user guide separated into two sections, with > the two different audiences in mind. I feel this would enable new > users of the library to have a more targeted introduction to some of > the neat features without getting bogged down in details they are > unlikely to need (or comprehend). > > I am very happy to have a go at this and put up a set of suggested > changes but I would value input from the community on this approach > and my category suggestions before I submit a pull request. > > many thanks > mark > > > -- > October Webinars: Code for Performance > Free Intel webinars can help you accelerate application performance. > Explore tips for MPI, OpenMP, advanced profiling, and more. Get the > most from the latest Intel processors and coprocessors. See abstracts > and register > > http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk > ___ Matplotlib-devel > mailing list Matplotlib-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/matplotlib-devel -- Android is increasing in popularity, but the open development platform that developers love is also attractive to malware creators. Download this white paper to learn more about secure code signing practices that can help keep Android apps secure. http://pubads.g.doubleclick.net/gampad/clk?id=65839951&iu=/4140/ostg.clktrk ___ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
