On call: Thomas, Eric, Ryan, Jody, Antony (later half)
## Documentation
Thomas reported that there is a fund for a mini-workshop to scope out documentation changes. Plan was to use that to write a proposal to fund a book.
- Eric expressed some reservations about a book, given the state of flux some parts of Matplotlib are in.
- Jody noted that beyond the book, a shorter ?getting started? guide on the webpage would still be desirable:
ACTION: Jody to co-ordinate a couple of outline documents that could start outlining both of these projects before any meeting.
There was also some discussion of online documentation technology:
- Notebooks (via nbsphinx: https://nbsphinx.readthedocs.io)
- hard to make PRs with. Diffs are a mess in GitHub.
- Can?t use emacs (easily)
- RST-based, with plot directive:
- python authoring less than desirable
- Sphinx-gallery based:
- rst authoring less than desirable
- sphinx gallery has very restricted ordering methods (file size and alphabetical)
More call notes, this time from a more definitive source @tacaswell!
- discussion about how to manage
- discussion about docs
- TAC: we have money to organize a mini-conference (from active state)
- EF: are we settled enough to do this? Do we want to leave it more dynamic?
- discoverability is mostly just google
- our API is overly complicated and organically grown
- major barrier to discoverability / usability
- maybe we want to clean up the API (aggressively?) first
- leads to questions about to define the agenda of mini-workshop
- JK: need an intermediate between what we have and a 200 page book
- need to order the sphinx-gallery entries
- EF: consider reverting the tutorials as sphinx-gallery
- need more control of ordering, but works well for examples
- wrong tool for tutorials
- look into sphinx-notebook
- move back to plain sphinx?
- TAC: we need to develop agenda for mini-workshop that addresses the above
- EF: before workshop is there a way to gather user requirements?
- TAC: user interviews, plausible, may also be part of work, can start now.
- JK: we can start collecting comments ahead of time
- JK will work on managing this!
···
On 31 Jan 2018, at 10:41, Jody Klymak <jklymak at uvic.ca> wrote:
Hi all,
Call notes from Monday?s call.
Cheers, Jody
On call: Thomas, Eric, Ryan, Jody, Antony (later half)
## Documentation
Thomas reported that there is a fund for a mini-workshop to scope out documentation changes. Plan was to use that to write a proposal to fund a book.
- Eric expressed some reservations about a book, given the state of flux some parts of Matplotlib are in.
- Jody noted that beyond the book, a shorter ?getting started? guide on the webpage would still be desirable:
ACTION: Jody to co-ordinate a couple of outline documents that could start outlining both of these projects before any meeting.
There was also some discussion of online documentation technology:
- Notebooks (via nbsphinx: https://nbsphinx.readthedocs.io)
- hard to make PRs with. Diffs are a mess in GitHub.
- Can?t use emacs (easily)
- RST-based, with plot directive:
- python authoring less than desirable
- Sphinx-gallery based:
- rst authoring less than desirable
- sphinx gallery has very restricted ordering methods (file size and alphabetical)
- Jody noted that beyond the book, a shorter ?getting started? guide on the webpage would still be desirable:
There was an attempt at integrating Nicolas Rougier's excellent
matplotlib tutorial to the doc. I believe he had given permission to
do so, and that the amount of work required to merge the tutorial was
extremely small.
Cheers,
N
···
ACTION: Jody to co-ordinate a couple of outline documents that could start outlining both of these projects before any meeting.
There was also some discussion of online documentation technology:
- Notebooks (via nbsphinx: https://nbsphinx.readthedocs.io)
- hard to make PRs with. Diffs are a mess in GitHub.
- Can?t use emacs (easily)
- RST-based, with plot directive:
- python authoring less than desirable
- Sphinx-gallery based:
- rst authoring less than desirable
- sphinx gallery has very restricted ordering methods (file size and alphabetical)
I missed the discussion about the docs, so
1. s-g is great for standalone examples but I would also prefer plain rst
for long tutorials (with e.g. vim-restructuredtext I can have both syntax
highlighting of rst parts in rst and python code-blocks in python (and
likewise for other languages) if the file is rst; for a .py file there is
no special recognition of rst markup by the editor).
2. any specific points about "python authoring less than desirable" for
rst? what functionalities would be desirable?
possible relevant links (some already mentioned above): https://nbsphinx.readthedocs.io/en/0.3.1/
Antony
2018-01-31 13:10 GMT-08:00 Jody Klymak <jklymak at uvic.ca>:
More call notes, this time from a more definitive source @tacaswell!
- discussion about how to manage
- discussion about docs
- TAC: we have money to organize a mini-conference (from active state)
- EF: are we settled enough to do this? Do we want to leave it more
dynamic?
- discoverability is mostly just google
- our API is overly complicated and organically grown
- major barrier to discoverability / usability
- maybe we want to clean up the API (aggressively?) first
- leads to questions about to define the agenda of mini-workshop
- JK: need an intermediate between what we have and a 200 page book
- need to order the sphinx-gallery entries
- EF: consider reverting the tutorials as sphinx-gallery
- need more control of ordering, but works well for examples
- wrong tool for tutorials
- look into sphinx-notebook
- move back to plain sphinx?
- TAC: we need to develop agenda for mini-workshop that addresses the
above
- EF: before workshop is there a way to gather user requirements?
- TAC: user interviews, plausible, may also be part of work, can start
now.
- JK: we can start collecting comments ahead of time
- JK will work on managing this!
>
> Hi all,
>
> Call notes from Monday?s call.
>
> Cheers, Jody
>
>
> On call: Thomas, Eric, Ryan, Jody, Antony (later half)
>
> ## Documentation
>
> Thomas reported that there is a fund for a mini-workshop to scope out
documentation changes. Plan was to use that to write a proposal to fund a
book.
> - Eric expressed some reservations about a book, given the state of
flux some parts of Matplotlib are in.
> - Jody noted that beyond the book, a shorter ?getting started? guide on
the webpage would still be desirable:
>
> ACTION: Jody to co-ordinate a couple of outline documents that
could start outlining both of these projects before any meeting.
>
> There was also some discussion of online documentation technology:
> - Notebooks (via nbsphinx: https://nbsphinx.readthedocs.io)
> - hard to make PRs with. Diffs are a mess in GitHub.
> - Can?t use emacs (easily)
> - RST-based, with plot directive:
> - python authoring less than desirable
> - Sphinx-gallery based:
> - rst authoring less than desirable
> - sphinx gallery has very restricted ordering methods (file size
and alphabetical)
>
> ## Release 2.2
>
> Various Release-Critical PRs were looked at.
>
>
> --
> Jody Klymak
> Jody M. Klymak - UVic Ocean Physics
>
>
>
>
>
> _______________________________________________
> Matplotlib-devel mailing list
> Matplotlib-devel at python.org
> Matplotlib-devel Info Page
I think all that was meant was that you can?t easily syntax highlight python in rst in most editors (not to start a vi/emacs thread ;-))
Personal opinion: I can?t write/compile an rst snippet in a reasonable timeframe: I?m not smart enough to write anything correctly the first time, so I prefer to hack. My computer is pretty good, but it takes 12 minutes to compile the docs, even if I make one small change. If there were a way to compile one file at a time, or if the doc build were smart enough to keep track of what has changed and what hasn?t it?d make editing in rst a lot easier.
Cheers, Jody
···
On 31 Jan 2018, at 15:07, Antony Lee <antony.lee at berkeley.edu> wrote:
2. any specific points about "python authoring less than desirable" for rst? what functionalities would be desirable?
Screenshot just for the record: left is "out-of-the-box" vim with no
customizations (vim -u NONE + :syntax on; which already has syntax
highlighting out of the box for python blocks); right is my setup (using
vim-restructuredtext HEAD).
I agree that the very slow edit-compile cycle for sphinx is less than
optimal. If you are just working on the rst part of a single file, you can
sort-of get away with rst2html (ships with docutils, bound to `:make` on my
vim setup), which will spew out tons of errors because it doesn't know any
sphinx constructs, but will still let you check the basic markup part. You
can also check docstrings that way by just processing the docstring in a
separate file with rst2html.
Antony
2018-01-31 15:15 GMT-08:00 Jody Klymak <jklymak at uvic.ca>:
>
> 2. any specific points about "python authoring less than desirable" for
rst? what functionalities would be desirable?
I think all that was meant was that you can?t easily syntax highlight
python in rst in most editors (not to start a vi/emacs thread ;-))
Personal opinion: I can?t write/compile an rst snippet in a reasonable
timeframe: I?m not smart enough to write anything correctly the first
time, so I prefer to hack. My computer is pretty good, but it takes 12
minutes to compile the docs, even if I make one small change. If there
were a way to compile one file at a time, or if the doc build were smart
enough to keep track of what has changed and what hasn?t it?d make editing
in rst a lot easier.
- Jody noted that beyond the book, a shorter ?getting started? guide on the webpage would still be desirable:
There was an attempt at integrating Nicolas Rougier's excellent
matplotlib tutorial to the doc. I believe he had given permission to
do so, and that the amount of work required to merge the tutorial was
extremely small.
Yes, and I can help with the integration as well (the tutorial needs an update anyway).
Nicolas
···
On 31 Jan 2018, at 22:54, Nelle Varoquaux <nelle.varoquaux at gmail.com> wrote:
Cheers,
N
ACTION: Jody to co-ordinate a couple of outline documents that could start outlining both of these projects before any meeting.
There was also some discussion of online documentation technology:
- Notebooks (via nbsphinx: https://nbsphinx.readthedocs.io)
- hard to make PRs with. Diffs are a mess in GitHub.
- Can?t use emacs (easily)
- RST-based, with plot directive:
- python authoring less than desirable
- Sphinx-gallery based:
- rst authoring less than desirable
- sphinx gallery has very restricted ordering methods (file size and alphabetical)
I signed up to this group hoping to learn or contribute to interactive Matplotlib.
My interest is to make Matplotlib accessible to the blind students.
I have long been a user of Matplotlib but technically at intermediate level. I have been playing with the interactive version for about 6 months and trying it out with blind people.
I browsed through Nicolas' tutorial. It is very well written. However I did not find description about the interactive feature.
There are a few document on the interactive Matplotlib. It will be nice if some pages can be spent for the interactive Matplotlib and its use with sound and tts: I am using beeo sound in the "sound" and "winsound" packages and SAPI for TTS). There is an official tutorial at https://matplotlib.org/users/interactive.html
It will be nice to let readers know features using sound and tts. These features require knowledge on procedure to stop the sound/tts without destroying the session. I end up shutting ipyhton down and restarting.
Regards,
Tune Kamae
···
-----Original Message-----
From: Matplotlib-devel [mailto:matplotlib-devel-bounces+tune.kamae=gmail.com@python.org] On Behalf Of Nicolas Rougier
Sent: Thursday, February 1, 2018 12:19 PM
To: Nelle Varoquaux <nelle.varoquaux at gmail.com>
Cc: matplotlib development list <Matplotlib-devel at python.org>
Subject: Re: [Matplotlib-devel] Call notes 29 Jan
On 31 Jan 2018, at 22:54, Nelle Varoquaux <nelle.varoquaux at gmail.com> wrote:
- Jody noted that beyond the book, a shorter ?getting started? guide on the webpage would still be desirable:
There was an attempt at integrating Nicolas Rougier's excellent
matplotlib tutorial to the doc. I believe he had given permission to
do so, and that the amount of work required to merge the tutorial was
extremely small.
Yes, and I can help with the integration as well (the tutorial needs an update anyway).
Nicolas
Cheers,
N
ACTION: Jody to co-ordinate a couple of outline documents that could start outlining both of these projects before any meeting.
There was also some discussion of online documentation technology:
- Notebooks (via nbsphinx: https://nbsphinx.readthedocs.io)
- hard to make PRs with. Diffs are a mess in GitHub.
- Can?t use emacs (easily)
- RST-based, with plot directive:
- python authoring less than desirable
- Sphinx-gallery based:
- rst authoring less than desirable
- sphinx gallery has very restricted ordering methods (file
size and alphabetical)
Yes, and I can help with the integration as well (the tutorial needs an update anyway).
Speaking personally, I think that was exactly the scope I had in mind when I said we could use something between the very short and somewhat idiosyncratic intros we have now and a 200-page book. If you were willing to work that into the official docs it?d be a huge contribution.
My only quibble is I somewhat prefer steering people away from the pyplot API, just because I think it becomes limiting.
Looking at the doc tree, it seems that if this tutorial could be put in `doc/users/` we could TOC it right under ?Installing? as ?Getting Started Guide? or ?Introductory Tutorial".
I?m not sure what machinery to use to author it in.
The nice thing about using sphinx-gallery is that you get a downloadable *.py and Ipython Notebook. If you go this route, it would live in `tutorials/introductory` and we could link directly in the table of contents.
Note there is an existing `tutorials/introductory/usage.py` that starts out OK, but then has some esoterica tacked on the end. I think your tutorial is nicer. But the image at the start of `tutorials/introductory/usage.py` is quite nice?
If you aren?t up for doing the conversion yourself, I?m happy to help, or I?m sure others are.
Cheers, Jody
···
On 1 Feb 2018, at 07:05, Jody Klymak <jklymak at uvic.ca> wrote:
Yes, and I can help with the integration as well (the tutorial needs an update anyway).
Speaking personally, I think that was exactly the scope I had in mind when I said we could use something between the very short and somewhat idiosyncratic intros we have now and a 200-page book. If you were willing to work that into the official docs it?d be a huge contribution.
My only quibble is I somewhat prefer steering people away from the pyplot API, just because I think it becomes limiting.
Thanks! Jody
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel at python.org Matplotlib-devel Info Page
FWIW, looking at the history confirmed what I remembered : the tutorial
under its current form was introduced by Chris Holdgraf, who made a
significant part of the documentation work with Nelle V. when we
switched to sphinx-gallery a while ago. Nevertheless the picture
?Anatomy...? had already been there in the gallery thanks to Nicolas R.
Cheers,
Adrien
···
On 02/01/2018 02:24 PM, Jody Klymak wrote:
Maybe the original `usage.py` is his as well?
Cheers, Jody
On 1 Feb 2018, at 13:48, vincent.adrien at gmail.com wrote:
On 02/01/2018 10:02 AM, Jody Klymak wrote:
But the image at the start of `tutorials/introductory/usage.py` is quite nice?
Well, if I remember correctly, that is Nicolas who created that picture !
Adrien
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel at python.org Matplotlib-devel Info Page
!