[Matplotlib-devel] Call notes 29 Jan

classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

[Matplotlib-devel] Call notes 29 Jan

Jody Klymak
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    
http://web.uvic.ca/~jklymak/





_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Call notes 29 Jan

Jody Klymak
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 <[hidden email]> 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)
>
> ## Release 2.2
>
> Various Release-Critical PRs were looked at.
>
>
> --
> Jody Klymak    
> http://web.uvic.ca/~jklymak/
>
>
>
>
>
> _______________________________________________
> Matplotlib-devel mailing list
> [hidden email]
> https://mail.python.org/mailman/listinfo/matplotlib-devel

--
Jody Klymak    
http://web.uvic.ca/~jklymak/





_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Call notes 29 Jan

Nelle Varoquaux
In reply to this post by Jody Klymak
>   - 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)
>
> ## Release 2.2
>
> Various Release-Critical PRs were looked at.
>
>
> --
> Jody Klymak
> http://web.uvic.ca/~jklymak/
>
>
>
>
>
> _______________________________________________
> Matplotlib-devel mailing list
> [hidden email]
> https://mail.python.org/mailman/listinfo/matplotlib-devel
_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Call notes 29 Jan

Antony Lee
In reply to this post by Jody Klymak
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?

Antony

2018-01-31 13:10 GMT-08:00 Jody Klymak <[hidden email]>:
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 <[hidden email]> 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)
>
> ## Release 2.2
>
> Various Release-Critical PRs were looked at.
>
>
> --
> Jody Klymak
> http://web.uvic.ca/~jklymak/
>
>
>
>
>
> _______________________________________________
> Matplotlib-devel mailing list
> [hidden email]
> https://mail.python.org/mailman/listinfo/matplotlib-devel

--
Jody Klymak
http://web.uvic.ca/~jklymak/





_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel


_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Call notes 29 Jan

Jody Klymak


> On 31 Jan 2018, at 15:07, Antony Lee <[hidden email]> wrote:
>
> 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.  

Cheers,  Jody
_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Call notes 29 Jan

Antony Lee
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 <[hidden email]>:


> On 31 Jan 2018, at 15:07, Antony Lee <[hidden email]> wrote:
>
> 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.

Cheers,  Jody


_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel

Screenshot_20180131_152655.png (788K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Call notes 29 Jan

Nicolas P. Rougier
In reply to this post by Nelle Varoquaux


> On 31 Jan 2018, at 22:54, Nelle Varoquaux <[hidden email]> 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)
>>
>> ## Release 2.2
>>
>> Various Release-Critical PRs were looked at.
>>
>>
>> --
>> Jody Klymak
>> http://web.uvic.ca/~jklymak/
>>
>>
>>
>>
>>
>> _______________________________________________
>> Matplotlib-devel mailing list
>> [hidden email]
>> https://mail.python.org/mailman/listinfo/matplotlib-devel
> _______________________________________________
> Matplotlib-devel mailing list
> [hidden email]
> https://mail.python.org/mailman/listinfo/matplotlib-devel

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Call notes 29 Jan

Tune Kamae
Hi,

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=[hidden email]] On Behalf Of Nicolas Rougier
Sent: Thursday, February 1, 2018 12:19 PM
To: Nelle Varoquaux <[hidden email]>
Cc: matplotlib development list <[hidden email]>
Subject: Re: [Matplotlib-devel] Call notes 29 Jan



> On 31 Jan 2018, at 22:54, Nelle Varoquaux <[hidden email]> 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)
>>
>> ## Release 2.2
>>
>> Various Release-Critical PRs were looked at.
>>
>>
>> --
>> Jody Klymak
>> http://web.uvic.ca/~jklymak/
>>
>>
>>
>>
>>
>> _______________________________________________
>> Matplotlib-devel mailing list
>> [hidden email]
>> https://mail.python.org/mailman/listinfo/matplotlib-devel
> _______________________________________________
> Matplotlib-devel mailing list
> [hidden email]
> https://mail.python.org/mailman/listinfo/matplotlib-devel

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Call notes 29 Jan

Jody Klymak
In reply to this post by Nicolas P. Rougier



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
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Call notes 29 Jan

Jody Klymak
Dear Nicolas,

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 <[hidden email]> 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
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel

--
Jody Klymak    






_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Call notes 29 Jan

vincent.adrien@gmail.com
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
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Call notes 29 Jan

Jody Klymak
Maybe the original `usage.py` is his as well?

Cheers,  Jody

> On 1 Feb 2018, at 13:48, [hidden email] 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
> [hidden email]
> https://mail.python.org/mailman/listinfo/matplotlib-devel

--
Jody Klymak    
http://web.uvic.ca/~jklymak/





_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Call notes 29 Jan

vincent.adrien@gmail.com
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, [hidden email] 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
>> [hidden email]
>> https://mail.python.org/mailman/listinfo/matplotlib-devel
>
> --
> Jody Klymak
> http://web.uvic.ca/~jklymak/
>
>
>
>
>

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel