OK made a pull request with the first changes (1): #4187. Cheers, F
On 03/03/2015 10:56 PM, Benjamin Root wrote: > The website is generated by sphinx from the docstrings and other > components in the doc/ directory of the matplotlib project. The file for > the home page can be found: > https://github.com/matplotlib/matplotlib/blob/master/doc/_templates/index.html > > By the way, the file for the "Documenting mpl" page is here: > https://github.com/matplotlib/matplotlib/blob/master/doc/devel/documenting_mpl.rst > > And, like I said, even if you don't get around to actually making any > changes, at the very least, I would file these issues as "bugs" to our > issue tracker. > > Cheers! > Ben Root > > On Tue, Mar 3, 2015 at 4:40 PM, Fabio Zanini > <fabio.zan...@tuebingen.mpg.de <mailto:fabio.zan...@tuebingen.mpg.de>> > wrote: > > Hi Ben, > > Well, excellent or not I just hope it helps a bit. I can put some effort > if people agree that this is useful, though I am quite busy at the > moment. Who's currently actually managing the website? > > Thx! > F > > On 03/03/2015 21:33, Benjamin Root wrote: > > This is excellent insight! It should be fairly trivial to fix points 1 > > and 2, and I agree that it would make the page much more inviting to > > newcomers. > > > > Point 3 would take some time. I had never noticed that before. > > Personally, I think the issue about documentation isn't that it is > > boring (I actually find them interesting), it is that by the time one > > gets into a project to actually start contributing, you become immune to > > the deficiencies in the documentation. Insights like these from > > newcomers are like gold to those of us who have been around for a while. > > > > Feel free to either create some pull requests to address some of these > > points, or at least file some bug reports so that we don't completely > > forget this. I may even be able to pick up some of it once my book > > finalizes for printing in the next week or two. > > > > Cheers! > > Ben Root > > > > > > On Tue, Mar 3, 2015 at 2:35 PM, Fabio Zanini > > <fabio.zan...@tuebingen.mpg.de > <mailto:fabio.zan...@tuebingen.mpg.de> > <mailto:fabio.zan...@tuebingen.mpg.de > <mailto:fabio.zan...@tuebingen.mpg.de>>> > > wrote: > > > > Dear Thomas, > > > > Finally got some time to reply about the docs. My main point > is not > > about the API docs themselves, although they would need some > tuning à la > > MEP10. Rather, as Sebastian's doubts about pyplot/axes shows, I am > > considering an issue with the non-API part of the docs, i.e. > the user > > guide, tutorial, and website. > > > > MY OLD PROBLEM WITH THE DOCS > > > > Now I am more experienced with mpl so I just read the API docs and > > figure my way through, but at the beginning I remember that > whenever I > > was wondering about something I would quickly end up in either > of two > > places: > > > > - the pyplot API page: http://matplotlib.org/api/pyplot_api.html > > > > This is a giant blob of a page and takes several seconds just > to load. > > It's lacking any kind of menu or navigation help, just the > whole docs > > straight out - alphabetical order - and bam! > > > > - stackoverflow > > > > Here people give practical suggestions, but they are > inconsistent (some > > use pyplot, some axes methods, sometimes even more low-level > code). I > > mean, it does work, but it's messy and not very instructive > for newbies > > (imagine learning say chemistry from stackoverflow, not fun uh?) > > > > > > HOW TO MAKE IT BETTER > > > > This one's harder, but I'd have a couple of ideas: > > > > 1. better home page > > > > The beginner's guide should be accessible from the home page > in ONE > > click, possibly highlighted in a frame or so. It currently takes 3 > > clicks on small text hyperlinks to get to some introduction, > the pyplot > > tutorial: > > > > HOME -> DOCS -> BEGINNER'S GUIDE -> PYPLOT TUTORIAL > > > > (and it's not even the first link on those pages). Some quick > visual > > snippet (possibly interactive e.g. an IPython notebook?) and > maybe a > > video tutorial like golang would be helpful: > > > > http://golang.org/ > > > > 2. More navigation support on the pyplot API page > > > > I realize API docs need to be somewhat stiff in order to make > sure you > > find what you're looking for (alphabetical order and so), but some > > side-menu, quick example, or highlighting of the most common items > > (plot, scatter) would be useful. I've read the acorr API docs > 100 times > > by now, and never, ever used it ;-P > > > > 3. clear presentation of the protagonist (Axes) > > > > As far as I understand, the main object for the user is the > Axes class. > > For instance, does the code below look familiar to anyone? > > > > ax.plot(x, y) > > ax.scatter(x, y) > > ax.set_xscale('log') > > ax.set_xlabel('My x axis') > > ax.set_xticks(...) > > ax.legend() > > ax.set_title('My title') > > ax.grid(True) > > > > Nonetheless, this kind of Axes-based coding is not even > mentioned in the > > beginner's guide. You may now think it's in the advanced guide > but, no! > > - the advanced guide only talks about "Artists" in general, > not the Axes > > in particular: "Artist tutorial", "Customizing your objects", etc. > > I am not criticizing past mainteners for this organization, > but I would > > support a more Axes-centric tutorial in the beginner's guide. > > > > As of the time issue, it's the usual problem, nobody wants to > do the > > docs because they are boring. It's true, it's a bit boring. > But that > > also depends a bit: writing API docs can be boring, but writing a > > tutorial for newbies can be fun! > > > > Cheers, > > Fabio > > > > > > > > ------------------------------------------------------------------------------ > > Dive into the World of Parallel Programming The Go Parallel > Website, > > sponsored > > by Intel and developed in partnership with Slashdot Media, is your > > hub for all > > things parallel software development, from weekly thought > leadership > > blogs to > > news, videos, case studies, tutorials and more. Take a look > and join the > > conversation now. http://goparallel.sourceforge.net/ > > _______________________________________________ > > Matplotlib-devel mailing list > > Matplotlib-devel@lists.sourceforge.net > <mailto:Matplotlib-devel@lists.sourceforge.net> > > <mailto:Matplotlib-devel@lists.sourceforge.net > <mailto:Matplotlib-devel@lists.sourceforge.net>> > > https://lists.sourceforge.net/lists/listinfo/matplotlib-devel > > > > > > > > ------------------------------------------------------------------------------ > Dive into the World of Parallel Programming The Go Parallel Website, > sponsored > by Intel and developed in partnership with Slashdot Media, is your > hub for all > things parallel software development, from weekly thought leadership > blogs to > news, videos, case studies, tutorials and more. Take a look and join the > conversation now. http://goparallel.sourceforge.net/ > _______________________________________________ > Matplotlib-devel mailing list > Matplotlib-devel@lists.sourceforge.net > <mailto:Matplotlib-devel@lists.sourceforge.net> > https://lists.sourceforge.net/lists/listinfo/matplotlib-devel > >
smime.p7s
Description: S/MIME Cryptographic Signature
------------------------------------------------------------------------------ Dive into the World of Parallel Programming The Go Parallel Website, sponsored by Intel and developed in partnership with Slashdot Media, is your hub for all things parallel software development, from weekly thought leadership blogs to news, videos, case studies, tutorials and more. Take a look and join the conversation now. http://goparallel.sourceforge.net/
_______________________________________________ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
