owned this note
owned this note
Published
Linked with GitHub
###### tags: `work-log` `gsod` `docs`
# GSOD 2021
Join Zoom Meeting
https://zoom.us/j/91573235246?pwd=TUQ2Mi9ablFzWU9xRzBZcnVrTzBaUT09
# 03/01/2021
## Agenda (Jerome)
### Updates
- #19183 (Getting Started)
- terminology updates
- Figure, Axes, Artists
- specific to MPL, Uppercase
- general language, lowercase
- Configuration error for `make html`
- command line output
```
/Users/jerome/Documents/matplotlib/doc/conf.py:19: MatplotlibDeprecationWarning:
The mpl_toolkits.legacy_colorbar rcparam was deprecated in Matplotlib 3.4 and will be removed two minor releases later. Please update your matplotlibrc.
import matplotlib
Configuration error:
There is a programmable error in your configuration file:
Traceback (most recent call last):
File "/Users/jerome/Documents/work/venv/lib/python3.9/site-packages/sphinx/config.py", line 319, in eval_config_file
execfile_(filename, namespace)
File "/Users/jerome/Documents/work/venv/lib/python3.9/site-packages/sphinx/util/pycompat.py", line 89, in execfile_
exec(code, _globals)
File "/Users/jerome/Documents/matplotlib/doc/conf.py", line 19, in <module>
import matplotlib
File "/Users/jerome/Documents/matplotlib/lib/matplotlib/__init__.py", line 833, in <module>
defaultParams = rcsetup.defaultParams = {
File "/Users/jerome/Documents/matplotlib/lib/matplotlib/__init__.py", line 836, in <dictcomp>
rcParamsDefault[key]),
File "/Users/jerome/Documents/matplotlib/lib/matplotlib/__init__.py", line 621, in __getitem__
return dict.__getitem__(self, key)
KeyError: 'axes.zmargin'
make: *** [html] Error 2
```
See also https://github.com/matplotlib/matplotlib/issues/19578
List-style syntax:
https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table
```
.. list-table:: Frozen Delights!
:widths: 15 10 30
:header-rows: 1
* - Treat
- Quantity
- Description
* - Albatross
- 2.99
- On a stick!
* - Crunchy Frog
- 1.49
- If we took the bones out, it wouldn't be
crunchy, now would it?
* - Gannet Ripple
- 1.99
- On a stick!
```
can be fixed by reinstalling (`pip install -e .`)
### Planned Tasks
- [x] fix error
- [x] resolve/change additional comments on [#19183](https://github.com/matplotlib/matplotlib/pull/19183)
- [ ] [Choosing Colormaps in Matplotlib](https://matplotlib.org/stable/tutorials/colors/colormaps.html#sphx-glr-tutorials-colors-colormaps-py)
# 02/22/2021
## Agenda (Jerome)
### Updates
- Addressed comments from Tim on [#19183](https://github.com/matplotlib/matplotlib/pull/19183)
- discussion with devs for standardization of terms
- tech writing stance: document whatever people are using regularly and is clear
- getting_started.py
- update homepage to link to getting_started guide
- user's guide is currently a colelction
- usage guide
- have not taken action yet
### Planned Tasks
- [ ] resolve/change additional comments on PR
- [ ] “Figure” for “Matplotlib” figures. “figure” for general figures, and ``Figure`` when discussing the class.
- [ ] [Choosing Colormaps in Matplotlib](https://matplotlib.org/stable/tutorials/colors/colormaps.html#sphx-glr-tutorials-colors-colormaps-py)
# 02/7/2021
## Agenda (Bruno)
- [ ] Continuing discussion on LineStyle from previous week.
- [ ] Do we return LineStyle from Line2D.get_linestyle() or `LineStyle._linestyle_spec` (i.e. what the user passed in).
- [ ] tl;dr: `__eq__` controls `==` and `in [...]`, `__hash__` controls dict access and `in {...}`
- [ ] LineStyle('-') == Linestyle('solid')
- [ ] 'solid' == LineStyle('-')
- [ ] (0, None) == LineStyle('solid')
- [ ] 'solid' == (0,None) (no)
- For `__eq__`, we can do `self.get_dashes() == LineStyle(other).get_dashes()`
- Python says if you have `__eq__` and `__hash__` for class `X` then:
- `X(a) == X(b)` => `hash(X(a)) == hash(X(b))`
- BUT this also must be true: `X(a) == b` ==> `hash(X(a)) == hash(b)`
- [ ] In short, while we can be "clever" with `__eq__` (because `other` lets us "infer" what the user is tryign to do), we have to actually make a hard choice with `__hash__`:
- [ ] Always hash the (offset, onoffseq)
- [NOPE, have to implement `__hash__` to match `__eq__`] Hash the normalized name if it exists, otherwise the (offset, onoffseq)
```python
ex_list1 = ['solid', 'hi']
ex_list2 = ['-', 'hi']
ex_list3 = [(0, None), ]
demo = {'-': 1, 'solid': 2, (0, None): 3}
s_short = LineStyle('-')
s_long = LineStyle('solid')
# weird one
assert demo[s_short] == 2
# everything else as expected
assert demo[s_long] == 2
for s in [s_long, s_short]:
for ex_list in [ex_list1, ex_list2, ex_list3]:
assert s in ex_list
```
- [NOPE] Hash whatever the user passed in
```python
assert demo[s_short] == 1
assert demo[s_long] == 2
```
- TOM: we should give up fuzzy equality before hashability.
- Bruno: won't a user be upset if they type:
- `test = {'red': 1, 'blue': 2, (255, 0, 0): 3}`
- `test[Color('red')] # always keyerror`
- Hannah:
```python
def is_alias(self, other):
return self == LineStyle(other)
def __eq__(self, other):
if not isinstance(other, LineStyle):
return False
return self.get_dashes() == other.get_dashes()
def __hash__(self):
return hash(self.get_dashes())
```
- TOM: "You can opt into the new stuff by passing us the new stuff."
- [ ] Path area PR? Blocking on MarkerStyle refactor...
[docs](https://docs.python.org/3/reference/datamodel.html#object.__hash__)
> The only required property is that objects which compare equal have the same hash value;
>
### Off-topic
Artist reorg:
- "Bruno language":
- In what follows:
- X ^ Y means X + Y with all shareable properties held equal
- Drawables:
- Pickable = (pickradius, )
- Rasterizable = (antialiased, )
- Typical
- Line = Rasterizable + Path + (linewidth, linestyle, joinstyle, capstyle, edgecolor)
- FilledArea = Rasterizable + Path + (facecolor, Hatch)
- Fillstyleable = FilledArea + (fillstyle, altcolor)
- SolidDashLine(path) = Either\[Line(path, dashed=False), Line(path, dashed=True)\]
- Marker = Line ^ Fillstyleable
- Distributors:
- Limiter ((Data, Transform) -> Range)
- Ticker ((Range, Formatter) -> Partition)
- Formatter (Datum -> Label) + Optional\[ticker heuristic\]
- An optional width heuristic could obviate custom Ticker code for 99.9%.
- LayoutRect (See below)
- Current state:
- Patch(path) is an (UnmarkableLine(path), Optional\[FilledArea(path)\])
- Line2D(path) is a (Patch(path, fill=False), PatchCollection(offset=path))
- Tick is a (Gridline, TickLine, Label, IsMajor : bool)
- Ideally:
- Line2D(path) is a (Patch(path, fill=False), PatchCollection(offset=path))
Re: 2D layout
- 2D layout is hard...
...but at least we don't need to reflow. If I were designing mpl from scratch, here's how I would do it.
Matplotlib figures are made of a tree of "LayoutRect"s, where a LayoutRect is basically just a Bbox:
- LayoutRect = ((x, y), (width, height))
the offset (x, y) position of each LayoutRect is defined relative to the coordinate system of the parent LayoutRect.
- The top-level LayoutRect is called Figure.
The relationship between most nodes in this tree are highly constrained. A LayoutRect can have two types of children:
1. FixedChildren:
- Define a "RectGraph" to be a 2D grid of labels, where contiguous labels (i.e. MorphologicalComponents) are *required* to be convex.
- Picture the input to subplots_mosaic.
- The set of FixedChildren must be the connected components of a RectGraph.
- The "RectGraph" name is due to layout requiring only the directed, "edge colored" graph of LayoutRect's, where LayoutRect nodes are connected by edges of colors (left<->right, above<->below) when they share that type of edge.
2. FloatingChildren:
- An arbitrary number of unconstrained LayoutRects, positioned relative to the parent.
Each LayoutRect can have some optional constraints:
- FixedAspect
- FixedWidth
- FixedHeight
otherwise, (width, height) float to accomodate the requested size.
- NOTE: this means figsize is not known until Layout time.
The layout engine, in general, would simply solve each FixedChildren tree (starting at Figure and traversing down recursively) for its location. This would happen in a totally separate pass to drawing.
Notice in particular this would mean that each Drawable that relies on nonlinear transforms would need to manually define its extents (e.g. each CRS), optionally as a function of having an arbitrary linear transform applied afterwards (to allow it to be e.g. rotated/sheared and still be tightly layed out).
## Agenda (Jerome)
### Updates
- Resolved additional points for #19183
- Still more to do for`Axes contain Figure elements` discussion point
- "plot elements", excel chart = matplotlib plot, tableau items
- Rebased, but failing Azure
- [Link](https://dev.azure.com/matplotlib/matplotlib/_build/results?buildId=16874&view=results)
- I remember this happening before, not sure what I did to resolve it
- Ignore! It'll get taken care of down the line
### Planned Tasks
- [x] Resolve comments
- [x] Rebase, fix errors in checks
- [ ] Compare a draft for Usage Guide ideas/changes
# 02/1/2021
## Agenda (Bruno)
### Updates
- [ ] LineStyle "style" choices https://github.com/matplotlib/matplotlib/pull/18664
- [x] Should LineStyle's compare/hash equal based on their dash pattern, or should the named ones always be special snowflakes?
- [x] Proposal: `LineStyle('-') == LineStyle((0, (,)))` should evaluate to `True`.
- [ ] Downside: `LineStyle('-') == LineStyle((0, (,)))` can change if rcParams changes.
- [x] Should `LineStyle('-').is_dashed()` return False if `rcParams['lines.solid_linestyle']` is actually dashed?
- [x] `mpl.rcParams['lines.solid_linestyle'] = LineStyle((0, (1, 2, 3, 4))) # LineStyle('-').is_dashed => True`
- [ ] Proposal: yes, we should always report based on what will actually be rendered.
- [ ] TODO: document this (is an API change)
- [ ] LineStyle('-') is LineStyle('solid')
- [ ] `LineStyle: solid = 'solid'; _solid_alias = '-'`??
- [ ] The other approach not involving metaclasses, doesn't work if we mix-in str `LineStyle(str, Enum)`
```python
def __new__(cls, int_value, *value_aliases):
obj = object.__new__(cls)
obj._value_ = int_value
for alias in value_aliases:
cls._value2member_map_[alias] = obj
return obj
```
- [ ] TODO: write tests for all the equality/hashing cases
- [ ] TODO: The what, the why, the how. Be concise in PR.
- [ ] TODO: send in
### Updates
# 12/23/2020
## Agenda (Bruno)
### Updates
- [ ] Needs review, sphinx ext https://github.com/matplotlib/matplotlib/pull/19063
- https://github.com/matplotlib/matplotlib/pull/18544
- [ ] Needs discussion https://github.com/matplotlib/matplotlib/blob/e23afa27b7786183d273d200e5352ea41bd1af96/lib/matplotlib/_enums.py
- this guy is lost: `LineStyle.dashed`
- `LineStyle(LineStyle('dashed'))`
- `LineStyle(NamedLineStyle('dashed'))`
- `LineStyle((0, [1, 2, 3, 4]))`
- Want:
- `LineStyle([1, 2, 3, 4])`
- `LineStyle([1, 2, 3, 4], offset=2.1)`
- allowed, but not "needed" `LineStyle((2.1, [1, 2, 3, 4]))`
-
```python
ls = LineStyle('--')
isinstance(ls, Enum)
isinstance(ls, NamedLineStyle)
line = Line2D(x, y, ls=ls)
line.get_dashes() # returns default
mpl.rcParams('lines.dash_pattern') = [1, 2, 3, 4]
line.get_dashes() # returns [1, 2, 3, 4]
```
- LineStyle('dashed') ==/is LineStyle('--')
Not:
- LineStyle('--').__new__(...) = # magic
- Conclusion: above was well-meaning at best idea. Don't forget to move positivity check to creation time.
- Resolution
* no NamedLinestyle, just regular which stores for back compat the literal the user passed in and generates a Linestyle
* don't expose LineStyle, even though `with plt.rc_context(`
- We don't want any explicit dash-style. It's a subset of `LineStyle` and `LineStyle([1, 2, 3, 4])` without an explicit offset should work. See also https://github.com/matplotlib/matplotlib/issues/17483
# 12/23/2020
## Agenda (Jerome)
### Updates
- Feedback for getting_started
- matplotlib.matplotlib check fail for getting_started
- Azure pipelines, Build log #L36845
`The operation was canceled.`
- I don't know how to fix this.
- specifying_colors
- "CN" color spec process
- original docs say
`indexing is intended to occur at rendering time, and defaults to black if the cycle does not include color`
and
`"CN" colors are converted to RGBA as soon as the artist is created`
- is that different from what I wrote to replace it?
`Indexing occurs at rendering time and defaults to black if cycle does not include color.`
and
`"CN" colors convert to RGBA when creating Artists.`
- Same process, default for color
- at resolution time, look at global cycle, use Nth color
- should happen as early as possible, context manager, less boiler plate, discovery to push as early as possible, directly in inits and artists
- check where to call to RGBA, happen in init, plot or method, early
- if done in draw, late
- indexing is resolved at draw time (true and understandable yet inconsistent with what hoped for)
- No updates/changes to usage_guide yet, 2021
- Question: Is there a place that explains what all the Matplotlib checks do?
- table for files used, point to where they are
- purpose of ci tools
### Planned tasks
- [ ] Resolve check fails for getting_started
- [ ] fix issues with specifying_colors
## Agenda (Bruno)
### Updates
# 12/22/2020
- Completed tasks:
- ["Color" proposal for Markers](https://github.com/matplotlib/matplotlib/pull/10008#issuecomment-750450116). Which I claim ties into GSOD because `MarkerStyle` is a..."type". And it's currently not "used" in `scatter` and `Line2D`. Should probably centralize this color code, regardless of what it is, to avoid future inconsistency. (This ties into "Collection" issue below).
- General questions:
- Agreement that "Style" classes should be idempotent?
- I think so, since it saves a ton of logic like: ```if isinstance(ls, LineStyle): ls = ls else: ls = LineStyle(ls)```.
- MarkerStyle is currently not idempotent (and this [is dealth with various places](https://github.com/matplotlib/matplotlib/blob/2cfef7611da4019967dc0d8c846d3c05769ae440/lib/matplotlib/axes/_axes.py#L4505))
- TODO: make MarkerStyle copy nicely.
- LineStyle cannot subclass Enum directly, because we must be able to return a unique "custom" instance every time the user requests a LineStyle using a specific `onoffseq`. However, subclasses of `Enum` (specifically, classes with metaclass `EnumMeta`) force each instance of the class to be a singleton (one for each class attribute). In general, this is a problem with "extensible" types, i.e. those with a fixed set of strings as options *as well as* a more general fallback. For example, `MarkerStyle` ('x', 'o', ... OR an arbitrary `Path`), `LineStyle` (':', '-', ... OR an onoffseq). Non-extensible types (i.e. those that truly are a collection of fixed strings) do not have this problem. Some solutions.
- For non-extendable classes, subclass `Enum` (FillStyle, JoinStyle, CapStyle, etc.). For extendable classes just subclass `str` or similar. We can add Idempotency, but we probably aren't getting any benefit from singleton-ness anyway (no reason to compare two instances with `is`, right?)
- Pros: Simple. People know what an Enum is, and we can use them when they fit.
- Cons: To add "extensibility" to a class later, requires breaking `isinstance(js, Enum)`. Means `_enums.py` maybe not the best name.
- Always just subclass str, like `JoinStyle(str)`
- Pros: Still Idempotent. No issues with whether we choose Enum or str in MRO. Objects seriously just "look" like strings. No backcompat issues. `_strings.py` might still be a reasonable name.
- Cons: Individual strings no longer can get their own docstrings. But hey, I didn't even use this fact in #18544 anyway so...
- Subclass EnumMeta, and override the type-level `__new__` to remove the singleton property (so `JoinStyle('miter') is JoinStyle('miter')` will now be `False`).
- Pros: By defining our own metaclass, we can do exactly what we want.
- Cons: We have to use a metaclass.
- Even more cons: Not even an `Enum` anymore, technically, `isinstance(js, Enum)` being `False` wil probably be pretty surprising.
- TODO: Subclass Tuple for LineStyle. When possible still subclass Enum.
- Moving validation logic into a class plays poorly with Collections
- For *zorder*, *hatch*, *pickradius*, *capstyle*, *joinstyle*, and to some degree, "`MarkerShape`", this is not really a problem. Because each collection only wants one of them.
- But for color.....
- TODO: Make Color and ColorList
# 12/14/2020
## Agenda (Jerome)
### Updates
- Color PR
- 0,1 as black white respectively
- Compositing/blending for zorder
- Artists may not commute because blending depends on all artists covering pixel at that moment
- GSoD PR
- comments before or on same line
- Put into style guide
- Backends
- process is internal, not user facing
- Matplotblog post
### Planned Tasks
- [ ] Fixing previous PRs
- [ ] Usage Guide?
# 12/14/2020
## Agenda (Bruno)
### Updates
- [x] Merge JoinStyle/CapStyle post-CI?
- [x] MatplotlibDeprecationWarning should now subclass DeprecationWarning.
- [ ] LineStyle ready for review
- [ ] Hatch giving me issues...
- Started adding tests to verify that "new" method of adding hatch density works correctly in all backends (all good here)
- BUT, getting a significant number of plot differences in existing tests, even though my change should not affect those...and none of them "look" like they have to do with Hatching
- working on bisecting this issue...
- [ ] Discuss Hatch API?
### Planned
- [ ] Dig up deprecationwarning PR
- [ ] Rebase everything onto new Join/CapStyle
# 12/07/2020
## Agenda (Jerome)
### Updates
- Completed PR draft
- GSoD report finished and submitted
- GSoD evaluation returned
### Planned tasks
- [x] Matplotblog post, also elevator pitch
- [x] Color tutorials and formatting tables
# 12/02/2020
Postponed from Wednesday 11/30/2020.
## Agenda (Jerome)
### Updates
- Resolved comments from PR
- Discuss layout of Artist tables
- `subplot_mosaic` reference?
- References to `install` and `legend guide`
`external resources` only able to find
HTML link success
- moving getting_started.py to front of Introductory tutorials?
- Added examples to style_guide.rst
- codecov/project/tests failure?
### Planned tasks
- [x] Blog post?
- [x] PR draft to open
- [x] GSoD report
## Agenda (Bruno)
### Updates
- [ ] Some [misc style fixes](https://github.com/matplotlib/matplotlib/pull/19063) for [Join/Cap](https://github.com/matplotlib/matplotlib/pull/18544), CI?
- [ ] [Hatch](https://github.com/matplotlib/matplotlib/pull/19077/commits/55c4380d64eadb6d12e1abc803dc8da43fd6b23f) some API decisions?
### TODO
- [ ] Push up Color/LineStyle (already done, just needs to pass CI)
- [ ]
# 11/23/2020
## Agenda (Jerome)
### Updates
- Fixed PR for "Files changed" only to mess up again
- Support from Tom for branch resolution
- `git push origin` last night then saw
"Files changed `165`" again :frowning:
- Pie chart programming and information
- Keyword arguments & Artists as focus
- Much time spent learning and troubleshooting
individually
- Still unable to use module
``.. currentmodule:: getting_started``
``.. autofunction:: my_plotter``
```WARNING: autodoc: failed to import function 'my_plotter' from module 'getting_started'; the following exception was raised: No module named 'getting_started' ```
- style_guide.rst not included?
`checking consistency... /Users/jerome/Documents/matplotlib/doc/devel/style_guide.rst: WARNING: document isn't included in any toctree`
### Planned tasks
- [x] Fix "Files changed" from PR
- [x] Fill in examples for style guide
- [x] Complete draft for GSoD PR
# 11/16/2020
## Agenda (Jerome)
### Updates
- Blown up GitHub commits and mess of multiple files in PR
- [Getting Started GSoD #18873](https://github.com/matplotlib/matplotlib/pull/18873)
- How to fix? Should/Must? Importance of clean PR?
- getting_started.py building appropriately, detailed content w/ references
- Trouble with reST
- [Anatomy of a figure](https://matplotlib.org/gallery/showcase/anatomy.html?highlight=anatomy)
- Not able to reference in doc as ``:ref:`anatomy-of-a-figure` ``
- Current module for auto-document not sure how to use
- ``.. currentmodule:: getting_started``
``.. autofunction:: my_plotter``
- seeing
```WARNING: autodoc: failed to import function 'my_plotter' from module 'getting_started'; the following exception was raised: No module named 'getting_started' ```
- PDF available of built content, how best to share?
- lean style guide still pending, PR later today 11/16 as draft
## Planned Tasks
- [x] Continue draft PR of getting_started.py
- [x] Lean style guide PR
## Agenda (Bruno)
### Updates
- Deal with the devil.
- Did 0hrs this week, but now have 2wks off to dump into mpl.
## Planned Tasks
- Same as last week (Join/Cap, Hatch, LineStyle, Color)
- merge some old outstanding PRs (path stuff)
- review colorbar stuff and collections stuff
# 11/09/2020
## Agenda (Bruno)
### Updates
- Merged: [Deprecation machinery](https://github.com/matplotlib/matplotlib/pull/18817)
- Needs button hit: [Clean all warnings from docs](https://github.com/matplotlib/matplotlib/pull/18905), [tiny hatch docs fix](https://github.com/matplotlib/matplotlib/pull/18919)
- Needs rebase/revert: Hatch, LineStyle, Color
- In progress: Last round (?) of fixes to [JoinStyle/CapStyle](https://github.com/matplotlib/matplotlib/pull/18544)
### Planned Tasks
- "Finish" Join/Capstyle?
- Rebase/revert hell
## Agenda (Jerome)
### Updates
- New computer
- Creating workflow again from scratch
- Beneficial for refining details of successes
- Additional commits for [getting_started.py](https://github.com/matplotlib/matplotlib/pull/18873)
- Mistakenly included an upstream pull
- Unsure how to remove
- Troubleshooting plot visuals for `make html` when building docs for getting_started.py
- Faster way of building docs/build specific file?
- Discussion of importance of Axis/Artists for developing entry paths
- Omitted in draft of .py file
- How to incorporate it as library fundamentals
- Importance hierarchy: OO > Axis/Artists?
### Planned Tasks
- [x] Work on creating drafted visuals
- [x] Continue with getting_started.py PR
- [x] .rst file for lean style guide
# 11/02/2020
## Agenda (Jerome)
### Updates
- Less productive with current machine setup
- Older computer space and RAM management
- Fixing GitHub SSH keys
- [Getting Started PR](https://github.com/matplotlib/matplotlib/pull/18873)
- .py file with text and simple examples
- Formatting as well as layout planned
- what is it?
- what do i need to make it work? requirements
- how do i make it work?
- common plots
- Additional prose and examples to develop
- Need visual content draft
- Necessary edits for compliance
- One run fix of Usage Guide Edits
- Fixed errors
### Planned Tasks
- [ ] Revise Usage Guide Edits PR
- [x] Complete text blocks for Getting Started
- [x] Four images to draft for graphics/visual aids
### Final Deliverables:
* strong getting started to semi-replace/supplant usage guide
* w/ linkouts/signposts to resources in docs as needed
* emphasis on OO (stateless/ you control the state ) versus pyplot (stateful) + assumptions of data structures
* thinner advanced users/customizations
*
# 10/26/2020
## Agenda (Jerome)
### Updates
- Developing Entry Paths
- [Developing Entry Paths Outline](/THQ06upYSPucR9wqBcYLzg)
- [GSoD Matplotlib Documentation Style Guide](/ZSlGuDNXRbGBVg3WHaZuSA)
- Pull request
- Back and forth individual research on how to approach standards for writing
- Small changes
- looking for areas of improvement
- sentence structure
- replacing/removing idiomatic or cultural language
- Big changes, holding off for discussion
- discussion on direction
- influences from other documentation
- tieing in to lean style guide potential?
- authority on standardization
- GSoD mid-project survey
- Timeline projections
- Concerns
- Requests
### Planned Tasks
- Continue adding detail to outline and draft of Developing Entry Paths
- turn into draft getting started pr
- Develop ideas for visual aids/graphics
- Review PR and refine as requested
## Agenda (Bruno)
### Updates
- Got all the flake's passing and all the docs building again.
- Responded to Tim's comments on Join/CapStyle. (https://48272-1385122-gh.circle-artifacts.com/0/doc/build/html/api/\_types.html?highlight=\_types#module-matplotlib.\_types)
- Started Color/ColorCollection
- Public?
- Collection semantics or raise?
### Planned Tasks
- Update LineStyle PR to incorporate new Join/CapStyle feedback
- Finish Color/ColorCollection
# 10/20/2020
- [x] Starting next week, moving to Mon, same time.
## Agenda (Jerome)
### Updates
- Survey results:
- [Updated Spreadsheet](https://docs.google.com/spreadsheets/d/1z_bAu7hG-IgtFkM5uPezkUHQvi6gsWKxoDnh0Hz1K5U/edit?usp=sharing)
- [Open Questions Summary](https://docs.google.com/spreadsheets/d/15EzVNmWVn2SjCUBc-Kt5Y0_entLgvWRMRYy8syt_-Xg/edit?usp=sharing)
- Categories chosen based on themes of responses
- Sorted manually after additional reading
- Word frequency chart:
- 
- [Developing Entry Paths Outline](/THQ06upYSPucR9wqBcYLzg)
- Minor additions to detailed intro
### Planned Tasks
- Usage Guide page edits and PR
- Possible thin style guide
- Prose draft for outline
- Find key links of relevant information for Entry Paths
## Agenda (Bruno)
### Updates
- To discuss: docstring interpolation strategies, when to include valid values, etc.
- see https://github.com/matplotlib/matplotlib/pull/18544 for current strategy
- Tim: just call interp, not dedent_interpd
- All: use two different "lengths" of literal lists of interpolation
-
- this strategy breaks flake8 (again) https://github.com/matplotlib/matplotlib/pull/18544/checks?check_run_id=1282864840
- btw, how to do private base classes without getting `/home/bbeltr1/developer/matplotlib/lib/matplotlib/_types.py:docstring of matplotlib._types.CapStyle:1: WARNING: py:class reference target not found: matplotlib._types._AutoStringNameEnum`
- Just refer to it so it gets added to the index
- get/set pairs with "see also", presumably due to historically need to actually *find* the docs for something. can I remove as I obviate? Or keep for consistency?
- Besides docstring issues, we've got:
- JoinStyle/CapStyle ready for re-review.
- LineStyle basically there.
### Planned tasks
- Color?
# 10/13/2020
## Agenda (Jerome)
### Updates
- Results of survey: 207 responses as of 9:00am PST, no longer accepting additional responses
- [Spreadsheet link](https://docs.google.com/spreadsheets/d/1z_bAu7hG-IgtFkM5uPezkUHQvi6gsWKxoDnh0Hz1K5U/edit?usp=sharing)
### Planned tasks
- Refine outline for entry paths documentation plan
- Consolidate results for readability
- Continue working on Usage page for edits and language
# 10/6/2020
## Agenda (Jerome)
- vacation! (See you all next week :smile:)
- Survey results thus far:
- 198 responses as of 8:15am PST
- Puget Sound Python (PuPPy), /r/Python Discord, Matplotlib Twitter
## Agenda (Bruno)
- Technical issues:
- We currently allow rc linestyle to be specified as dashes, but not linestyles passed as arguments to e.g. `Line2D`. Is this intended behavior? Should I be accepting dashes in both places? In addition, rc accepts any upper/lower-case but that's not allowed other places.
- TOM: keep rc param behavior independent
- Goal is for construction of the class to be centralized validation (to avoid issues like the above), but construction of some classes depend on existence of rcParams (e.g. linestyle requires `rcParams['lines.dashed_pattern']`, etc)
- This is basically because we construct the entire rcParams at once (greedily) in `__init__` instead of lazily (as needed) after reading in the text.
- This strategy *necesitates* having separate:
- "constructors": that Pythonically implement the logic to take the rcParam input and construct the actual object. these are currently scattered throughout the code, mostly in `set_*` methods.
- validators: less-Pythonic throw-away functions that use type instrospection to (try to) predict if the later construction will work.
- Nothing is "wrong" with this, and I can make my "centralized classes" work in the current system by having a separate validator method which encodes the "type introspection"-style version of the logic separately. This just *feels* more brittle (although since at least they would be right next to each other in a single class, it'd definitely be better than the current situation).
- TOM: just defer lookup in the case of the string enum, then lookup in rcParams at artist construction time
- Confirmation that it seems like not a *Bad* idea to use these classes for more than validation? If it really is the case that we don't want users to ever be returned instances of these classes, we should not convert to them internally, as then users will get them out if they call e.g. `get_linestyle`.
- To play devil's advocate, users probably do ask for "color" objects a lot, so suddenly having to *unpack* the objects before using them again as numpy arrays of floats would probably break *a lot* of code.
- The reason I haven't been worried about this is I plan to mitigate it by making my color class as "transparent" as possible (subclass ndarray)
- Just wanted to bring this up early on (trying to attack the "hardest" cases first) to make sure this is all viable.
- TOM: stash the user's *actual* input, so we can return it for now. for the case of color, since we only actually *use* the internal representation inside of `draw`, which is the only place it's touched
- I hate string interpolation in docstrings as much as anybody, but one of the main impeti of this project was seeing how inconsistent the docs are w.r.t. parameter allowed values, defaults, etc. The question of *which* possible values to put in was a bit underemphasized on the call yesterday. In order from most to least "robust":
- go back to doing `dedent_interpd` string interpolation of the docs, and calling methods like `LineStyle.allowed_strings` to populate the `interpd` database
- move away from `dedent_interpd`, now that centralized classes hold the relevant strings, we can just import them and using mostly-standard formatting tools (basically just interpd but without the global database, this is guaranteed to always work because the presence of `%(Class)` in a module always means that module has to import that class anyway), e.g.:
```python
# in spines.py
from patches import Patches
...
def __init__(self, axes, spine_type, path, **kwargs):
"""
...
Other Parameters
----------------
**kwargs
{patch_properties}
...
"""
# function internals
...
# thin wrapper to `.format`
_format_indented(__init__.__doc__, 'patch_properties', Patches._property_docs)
# then in patches.py:
from _types import Color, LineWidth, LineStyle, AntiAliased, Hatch, Fill, Capstyle, JoinStyle
```
- just put in every allowed value by hand at every point in the docs
- ad-hoc choose which allowed values to put in at which point in the docs? (current situation)
- My impression is that a good "goal" for GSOD would be to:
- make `dedent_interpd` and `artist.kwdoc` unnecessary (not necessarily get rid of them, but make it just as easy to just refer to already-"linked" docs as described above)
- put complete, plainwords description of what `_types` classes are required by each public class (e.g. currently a "Patch" claims to just be an artist with a face and edge color, but like, it's more like an artist with a "fill" and a "border line", which means it can be described as "fill" `_types` + `Line2D`)
- Planned tasks:
- Do all the above to Join/CapStyle
- return string version from get_*
- use interpd to list possible string inputs consistently
- Finish LineStyle + Color
- ....many TODOs.
# 9/29/2020
## Agenda (Shared)
## Agenda (Bruno)
### Updates
- Minor setback, GCC updated underneath me yesterday (been using Sun-Tues for GSOD), [breaking my local copy of matplotlib](https://bugs.archlinux.org/task/67686?string=lto1+&project=1&type%5B0%5D=&sev%5B0%5D=&pri%5B0%5D=&due%5B0%5D=&reported%5B0%5D=&cat%5B0%5D=&status%5B0%5D=open&percent%5B0%5D=&opened=&dev=&closed=&duedatefrom=&duedateto=&changedfrom=&changedto=&openedfrom=&openedto=&closedfrom=&closedto=)
- A couple of trivial PRs.
- Finished CapStyle/JoinStyle proposal (PR marked WIP until after this meeting).
### Planned tasks
- Respond to community comments for `JoinStyle`/`CapStyle`.
- Get `LineStyle`, `FillStyle` implemented.
## Agenda (Jerome)
### Updates
- Setback of Github directory mixup, commit confusion, and clarifications
- Short on feedback for questionnaire, minor changes only
- Draft still up for review **[Matplotlib User Questionnaire](https://docs.google.com/forms/d/1ZYEFkBAQwlzeK_iPVxPqRzleX30RFGjJ3Y6HcY5sD3M/edit)**
- Outline 60% complete, missing more advanced ideas for entry
- **[Developing Entry Paths Outline](/THQ06upYSPucR9wqBcYLzg)**
- Summary of interviews available
- **[Summary of Interviews from 9/15 - 9/22](/gg1QDrNXRZWWXwhMCH5OJw)**
### Planned tasks
- Out for meeting on 10/6 (wedding week!) will return 10/13
- Distribute this week, collect information from surveys to communities
- Complete usage guide PR for additional general edits
# 9/22/2020
## Agenda (shared)
* expectations on work hours per week?
## Agenda (Bruno)
* Updates
* Only got 5-10hrs in this week, but last major paper on my plate is now out with co-authors for "final touches" (this morning), so I will have much more time moving forward.
* One micro-PR, responded to comments on an old non-docs PR, then set up the below for discussion:
* How to structure new docs ([using simple example of `joinstyle`](https://github.com/matplotlib/matplotlib/pull/18544))
* Recall stated goals:
* One "click" maximum to reach full documentation, zero clicks for experienced users.
* Ease of use for multiple user types:
* Terminal-based `help()` and IPython `?name` calls.
* Web-browser docs scrollers.
* Beginner and advanced users.
* Prioritize "simplest" use-case. (i.e. have the top-level summary or simplest explanation right at the top). *Most* users shouldn't have to scroll.
* Carefully document even the most complicated use-case (in increasing order w.r.t. `complexity * rarity`, so that a user can learn advanced Matplotlib features just by scrolling down.
* Set-backs/Questions:
* Not clear how to cleanly say "look online for image or run this code".
* Need to read into how gallery works, nbd, just didn't have time this morning.
* How obnoxious should I be about re-linking things, like `Path` in the linked PR?
* Tense? Literary first/third or second person?
* Where to put new classes (universally applied ones in backend_bases? specific ones in the appropriate module?)
* Current "list" of "pseudotypes":
* capstyle
* joinstyle
* fillstyle
* linestyle
* bounds
* extents
* colors/lists of colors
* colornorm/colormap
* ticks/locators/formatters
* hatch
* drawstyle
and some that are already classes:
* bbox
* markerstyle
### Planned tasks
* Move new thin classes into private module
* Wrap *everything*, so that we can include demos, validators, etc even for simple parameters
*
## Agenda (Jerome)
### Updates
- ~10 hours or so of work, including notes from interviews with three people and creating questionnaire
- Former instructor, data scientist, M.S. grad in CS
- Rounded out patterns and similarities in responses
- Documented feedback for unique takes
- **[Google Forms](https://docs.google.com/forms/d/1ZYEFkBAQwlzeK_iPVxPqRzleX30RFGjJ3Y6HcY5sD3M/edit?usp=sharing)** draft ~85% complete for review
- Seven questions (only one short answer text), still tentative for more, though no more than 10 (and two short answer)
- No PR work done since last meeting
### Planned tasks
- Compile notes for presentation and additional review
- Distribute Forms to communities
- After feedback; PuPPy group, Reddit communities, open to sharing with other organizations/communities
- Work on Docs as available
- Develop outline for Core entry user content
- Identify user confidence levels
- Collect relevant links to documentation
- Support topic organization with introductory content
# 9/15/2020
## Goals
* Bruno - still exist (buried under school stuff)
* Jerome - go through and put in PRs for improving langaguge in the existing docs
*
## Agenda
* reporting?
* Consensus: Weekly meetings fine for now. Maybe towards the end we can tighten up if needed.
* tentative plans for the first month
* Bruno
* First week: Make detailed list of API surface that my GSOD will aim to standardize documentation for. Send in PRs for "simple" cases ('joinstyle', 'capstyle', etc.) that just need a dedicated class.
* Second week: Finish collating existing documentation that corresponds to each "pseudoclass". Proposal PR for first example of combining these into centralized place.
* Moving forwards: ...more of the same?
* parameter list: https://docs.google.com/spreadsheets/d/1YRSyqV1MToC3BEvE9eAEITAI4yKhjeu2sUNZtd8tTmY/edit?usp=sharing
* Jerome
* usability testing w/ some of the learner communities -
* Puget sound Python (what they'd recommend)
* maybe reddit/internet based user groups
* https://gitter.im/matplotlib/community/share out to the community via twitter/etc
* resources on matplotlib entry paths
* videos
## 9/8/2020
* Jerome (w/ Bruno's help) https://github.com/matplotlib/matplotlib/pull/18435
* prelim plans:
* Bruno - run through the docs filling in gaps, focus on internal implicit contracts in API
* Jerome - putting in small PRs
* Hannah & Bruno talked about topology (v4) & how that may intersect w/ documenting types/aesthetic primatives
*
## 9/3/2020
### linking between dev/release/old docs
* should the how-to-contribute docs only link to the dev version of docs? (Consensus is YES).
### docs that are tagged to versions vs not
#### tagged to versions
* api docs
* tutorials
* user docs
* gallery
#### not tagged to versions
* goverenance
* code of conduct
* contributing
* socials/community
### search engines redirecting to old versions
#### already been done
* telling search engine to index
#### have prs
* adding banner directly to HTML (like py2)
#### things to do
* change docs deployment process to use --delete on rsync w/o dystroying non-build files
### computer/environment specific install issues
* sign post when/where to look outside
### for next week
* @bruno - get matplotlib PRs merged
* @jerome - attempting to edit docs on own from build + navigating github (working w/ bruno) + good workflow
* make a PR w/ banner on contributing folks to look at the devdocs -
* tag @timhoffm and @story645
Sign in with Wallet
