My proposal was centered around integrating the API documentation with a large swath of existing tutorials and examples by attempting to systematically document what I will call Matplotlib’s “implicit types”. These are a set of core concepts which, due to their “duck type”-heavy nature, have not yet merited their own proper class, but nonetheless are commonly accepted as inputs to a variety of Matplotlib routines internally, and whose documentation is currently scattered throughout docstrings, tutorials, and sometimes even just in examples.
The project led to multiple merged pull requests, and many technical challenges were overcome. Each “implicit” type that needed to be documented required the creation of a new bona-fide class, and this code had to retain backwards compatibility while adhering to the standards required for inclusion in the library. With the generous help of Hannah, Tim, and Tom, during we were able to hash out each of these problems during our weekly meetings and we now have a framework in place for how exactly these implicit types should be documented moving forwards. In addition to the new documentation and many small bugfixes to the documentation code, several inconsistencies in Matplotlib's internal behavior were found and documented as a result of the GSOD, and some of these currently have discussions open on Github centered around how to deprecate the inconsistent behavior.
Overall, I would say that GSOD was a success, albeit a measured one, since perhaps committing to such an expansive project in the quarter during which I also was finishing my PhD was a tad ambitious. That said, I have no intention of stopping work on this project when the official GSOD time is through, and I hope to see it to its full completion by the summer!
In reverse chronological order (omitting several non-GSOD-related PRs):
- #19418: a small bugfix in the docs build process on Windows
- #18544 : JoinStyle and CapStyle!
- #19063 : a CSS fix allowing our new centralized API examples to display correctly across different devices
- #18817 : a necessary deprecation to allow the JoinStyle and CapStyle classes to take over internally
- #18780 : update our CI to use the latest versions of the automated checking tools to allow some tricky contructions that I need for the API docs
- #18744 : Document how LogLocator's numticks works
- #18610 : Document our optional doc dependencies
- #18542 : Centralize joinstyle and capstyle validation in preparation for factoring it into a new class
- #18475 : Fix doc building behavior if no appropriate Latex compiler is present
- #18341 : Improve documentation for the process of submitting a PR.
- #19077 : A Hatch class, and related documentation on hatching in matplotlib.
- #17115 : A proposal for Bbox behavior, necessary before documentation of "extents" (x0, y0, w, h) and "bounds" (x0, y0, x1, y1).
- #18664 : LineStyle.
As laid out in my proposal, the types that remain to be documented are:
- Color and ColorList: because of a lack of Haskell-like dataclasses in Python, these would have to be done separately. Leaving Color for last turned out to be an excellent idea. It is arguably the most complex of the implicit types, and so the lessons we learned implementing Hatch, LineStyle, JoinStyle and CapStyle will come in handy as we move towards centralizing the color documentation.
- Miscellaneous "easy" classes: zorder, pickradius, fillstyle, drawstyle.
Minutes for our weekly meetings are public, and available at:
https://hackmd.io/cSNb2JhrSo26zJGag3bvLg