Menu
▾
▴
Re: [matplotlib-devel] API Documentation usability
|
From: Benjamin R. <ben...@ou...> - 2015-03-03 21:56:45
|
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 <fab...@tu...> 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 > > <fab...@tu... <mailto:fab...@tu...>> > > 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 > > Mat...@li... > > <mailto:Mat...@li...> > > 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 > Mat...@li... > https://lists.sourceforge.net/lists/listinfo/matplotlib-devel > > |
