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

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

fix error
resolve/change additional comments on #19183
Choosing Colormaps in Matplotlib

02/22/2021

Agenda (Jerome)

Updates

Addressed comments from Tim on #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

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)

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

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:

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

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 forAxes contain Figure elements discussion point
- "plot elements", excel chart = matplotlib plot, tableau items
Rebased, but failing Azure
- Link
- 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

Resolve comments
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
- Should LineStyle's compare/hash equal based on their dash pattern, or should the named ones always be special snowflakes?
  - Proposal: LineStyle('-') == LineStyle((0, (,))) should evaluate to True.
  - Downside: LineStyle('-') == LineStyle((0, (,))) can change if rcParams changes.
- Should LineStyle('-').is_dashed() return False if rcParams['lines.solid_linestyle'] is actually dashed?
  - 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)
```
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]))
```
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. 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)
  - 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

Merge JoinStyle/CapStyle post-CI?
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

Matplotblog post, also elevator pitch
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

Blog post?
PR draft to open
GSoD report

Agenda (Bruno)

Updates

Some misc style fixes for Join/Cap, CI?
Hatch 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
  Image Not Showing Possible Reasons
  - The image file may be corrupted
  - The server hosting the image is unavailable
  - The image path is incorrect
  - The image format is not supported
  Learn More →
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

Fix "Files changed" from PR
Fill in examples for style guide
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
- 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
    - 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

Continue draft PR of getting_started.py
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
Needs button hit: Clean all warnings from docs, tiny hatch docs fix
Needs rebase/revert: Hatch, LineStyle, Color
In progress: Last round (?) of fixes to JoinStyle/CapStyle

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
- 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

Work on creating drafted visuals
Continue with getting_started.py PR
.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
- .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
Complete text blocks for Getting Started
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
- GSoD Matplotlib Documentation Style Guide
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

Starting next week, moving to Mon, same time.

Agenda (Jerome)

Updates

Survey results:
- Updated Spreadsheet
- Open Questions Summary
  - Categories chosen based on themes of responses
  - Sorted manually after additional reading
Word frequency chart:
Developing Entry Paths Outline
- 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

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
Image Not Showing Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
)
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.:
```
# 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
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
Outline 60% complete, missing more advanced ideas for entry
- Developing Entry Paths Outline
Summary of interviews available
- Summary of Interviews from 9/15 - 9/22

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)
- 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 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

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`	在筆記中貼入程式碼
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.

tags: work-log gsod docs

GSOD 2021

03/01/2021

Agenda (Jerome)

Updates

Planned Tasks

02/22/2021

Agenda (Jerome)

Updates

Planned Tasks

02/7/2021

Agenda (Bruno)

Off-topic

Agenda (Jerome)

Updates

Planned Tasks

02/1/2021

Agenda (Bruno)

Updates

Updates

12/23/2020

Agenda (Bruno)

Updates

12/23/2020

Agenda (Jerome)

Updates

Planned tasks

Agenda (Bruno)

Updates

12/22/2020

12/14/2020

Agenda (Jerome)

Updates

Planned Tasks

12/14/2020

Agenda (Bruno)

Updates

Planned

12/07/2020

Agenda (Jerome)

Updates

Planned tasks

12/02/2020

Agenda (Jerome)

Updates

Planned tasks

Agenda (Bruno)

Updates

TODO

11/23/2020

Agenda (Jerome)

Updates

Planned tasks

11/16/2020

Agenda (Jerome)

Updates

Planned Tasks

Agenda (Bruno)

Updates

Planned Tasks

11/09/2020

Agenda (Bruno)

Updates

Planned Tasks

Agenda (Jerome)

Updates

Planned Tasks

11/02/2020

Agenda (Jerome)

Updates

Planned Tasks

Final Deliverables:

10/26/2020

Agenda (Jerome)

Updates

Planned Tasks

Agenda (Bruno)

Updates

Planned Tasks

10/20/2020

tags: `work-log` `gsod` `docs`