Documentation is critical for helping people use mpl effectively (or at
all). Our core documentation has many shortcomings, and needs much more
attention than it gets. But that's another topic.
This message is prompted by
https://github.com/matplotlib/matplotlib/pull/3088, which has led to the
suggestion that we make a separate repo for documenting examples that
might be too elaborate or specialized to go in the core, but that can be
more visible, more effective, and better-maintained if they are kept in
another repo in our github account. They could then be published
automatically using readthedocs.org.
The primary alternatives here are:
1) Continue with PR 3088 as-is, and encourage other such additions to
the core docs.
2) Redirect such contributions to http://wiki.scipy.org/Cookbook/Matplotlib.
3) Start a new repo on our github account, as suggested above.
The advantage of (1) is that it keeps everything together; the
disadvantage is that it makes the central mpl repo even more sprawling
and harder to coordinate for releases.
The advantage of (2) is that it already exists, and its wiki interface
might make contributions and updates easier. The disadvantage is that
it doesn't seem to get much maintenance, and it's wiki format is not as
nice as full Sphinx docs.
The advantage of (3) is that it encourages expansion of documentation
that can proceed independently of the core release schedule, and without
bloating the core.
With either (2) or (3), our core docs should point to the Cookbook location.
The key to making any of these options work well is participation; we
need people to keep working on improvements.
Eric
|
