Alright @timhoffm, these docs now look like what I would expect when I build them locally. Feel free to offer any feedback, but some points I'm most interested in your opinion are:

1. How to deal with "constructible-as". I made sure that everywhere which now takes a [Cap/Join]Style still takes the old string inputs by simply calling the new constructors immediately. This means that functions with those arguments will have Parameters entries which look like:

joinstyle : `JoinStyle` or {'bevel', 'miter', 'round'}, default: :rc:`patches.joinstyle`

or similar.

Frankly, this is totally fine, but for other types, like LineStyle, this will quickly get out of hand. I propose the following standard:
we list out both the "_types" type and the alternative options (e.g. LineWidth or float) unless that would make us overflow the line. This has the upside of keeping things as easy to discover as possible without sacrificing readability (and I would argue that if you don't know what all the options for e.g. LineStyle are, I do want to force you to click that link or type "help()" once more.

Another option is to do something similar to what numpy does, and have some syntax for "this parameter can be any type that can be passed directly to the constructor of X". "X-like", "X-able", "X-constructible" or something similar. This would make the above docstring look like

joinstyle : `JoinStyle`-like, default: :rc:`patches.joinstyle`

which is of course much shorter.

2. Obviously I'm a fan of your suggestion to call this module _types.py, but any other naming thoughts are more than welcome!

3. and finally, I guess do we want this to get "what's new"? I guess if we want this to be solely a documentation/internal validator mechanism for now, I could just make sure the entry emphasizes that this private module is open for use, but that it's name/etc. are liable to change in a future version?

CI failing on backends that I don't have installed locally (surprise). I'll do a better job of cleaning that up ASAP.

But this also goes to show that with this specific proposal, this is a major API change for people who write their own backends. I'll bring this up on the next call.

tl/dr;

Not yet decided. I have to think about this more. Everything below is just unstructured preliminary thoughts.

Private/public

I'm hesitant to make this public right now. Using these types on the front-end is a lot bulkier:

from matplotlib._types import JoinStyle
plt.plot(x, y, joinstyle=JoinStyle.miter)

instead of

plt.plot(x, y, joinstyle='miter')

I can't bring myself to recommending or even only showing the above.

Type documentation

In turn, if JoinStyle is not public, we should not announce it as a supported parameter type.

For completeness: If the types were public:

1. We should try not to overflow the line.
2. Explicit is better:
   If it matches on the line:

   joinstyle : `JoinStyle` or {'bevel', 'miter', 'round'}
   

   otherwise (we already use "array-like"):

   joinstyle : `JoinStyle`-like
   

Alternatives

If you are motivated to dive into sphinx roles:

joinstyle : :mpltype:`JoinStyle`

With a suitable rendered representation. The downside is that inline help does not have the explicit values.

There is the "provisional" label for making it semi-public if you want a middle ground.

I'm hesitant to make this public right now. Using these types on the front-end is a lot bulkier:

The way the type is constructed is completely transparent to the user. I would argue that even if this was fully implemented, we would still use the "string" versions in all of our examples, and encourage users to do so (due to the added conciseness), except in examples where there's an obvious readability benefit to constructing the type bit-by-bit (like making a complicated custom MarkerStyle).

in other words, this still works:

plt.plot(x, y, joinstyle='miter')

IMO the real issue isn't whether or not we promote this to our end users (since they are really not affected except for they get the extra option of passing in these guys as the explicit object if they really want), but whether we internally store the string (e.g. in GraphicsContextBase) or store the new Enum object (in which case third-party backends would have to add .name anywhere they use the JoinStyle as a dictionary key)...[see footnote]

I can't bring myself to recommending or even only showing the above.
The benefits are clearly not there for a simple case like JoinStyle, but the goal is to make objects like LineStyle more useable in addition to making their advanced features more discoverable (similarly to how MarkerStyle gets its own class, but nobody complains because you can still just pass 'o' or similar).

If you are motivated to dive into sphinx roles:

joinstyle : :mpltype:`JoinStyle`

This was an alternate proposal that I fully wrote up at one point. In the last dev call where this was discussed, it was decided that making them full classes makes more sense, as this gives us a place to put validators/serializers (since I'll be writing the validators anyway given that it's zero extra work once I commit to fully documenting these things).

@timhoffm if you think it would be worthwhile I'm happy to have this role implemented for Monday, since I've done the sphinx role dance before, if you think having these two options would aid discussion?

....

[footnote]
...although as a side note, we could even do an arbitrarily good job handling backcompat, by overwriting __hash__ and changing the default Enum dunder functions to be more friendly, e.g.:

def __eq__(self, other):
    try:
        other = self.__class__(other)
    except ValueError:
        return False
    return self == other

and so forth. I could make a "Wasn'tAClassBeforeBase" class to share all of these "fixes"....

I think this is useful, so long as the old behaviour is maintained of allowing a string. The point of making these public is that they will show up as their own thing in the docs.

OTOH, I don't know about calling this module "types". That is a pretty generic and loaded term in computing. style_classes? Dunno, but not types!

@jklymak We already have a style module. That name is taken and would be too confusing to be used with a different context.

Requirements

(sort of, style classes are already a solution, but hey)

• we want the style classes for internal stuff (validating, serializing, maybe as internal datatype)
• we want a dedicated place to put docs for these and have links from corresponding parameters.
• user should still only use the simple types (e.g. strings)

Proposed solution

1. Let's keep the style classes private. If users shouldn't use them, they don't need to know that there is a formal JoinStyle class. This also alleviates the module naming discussion.
2. Style classes collect all the desired functionality, including documentation.
3. We don't put the classes in our public docs using the standard sphinx API generation tools (these classes are private, see 1.). Instead, we need another mechanism to extract the documentation and put it on some pages, possibly a custom sphinx directive. To be decided whether these docs are the class docstring or some other string attached to the class.
4. We also need a mechanism to link types, possibly a sphinx role. Maybe (up for discussion):
   :mpltype:`joinstyle` with an option for :mpltype:`joinstyle {'miter', 'round', 'bevel'}` if we want to state explicit values for plaintext docs.

Defining own sphinx roles and directives is a bit more heavy-weight, but it allows us to use internal code structures and keep them completely hidden from the user.

But a counterpoint is that if we have public classes they could take kwargs on init. I imagine some of those have parameters that could be adjusted. We do exactly this for markers.

(Some of) the classes can still be made public if we feel that is beneficial.

I'd agree with you, if you hadn't just proposed a new sphinx directive and a new sphinx role. The more of these we have, the more fragile our development process is.

* user should still only use the simple types (e.g. strings)

@timhoffm, this phrasing is surprising to me, based on the concerns you voiced above, I would have expected you to say:

*user should still be able to use the simple types (e.g. strings)

I definitely agree with the latter, and I think no proposal can move forward that doesn't allow the user to still use the string syntax, but I don't see the danger/negative to allowing the user to use the new syntax, even if in this case it's strictly more verbose....

In particular, this would solve the tab-complete dilemma that I've seen you be actively involved in before, right? I mean if the user does take the time to from _types import *, then they can do ..., lw=5, joinstyle=JoinStyle.[TAB].

And as we all know, documentation-by-available-tab-completion-options is a real thing, and iirc Jedi is not stoked about getting this to work in general for string parameters (even with options listed in docstring?)

That is a pretty generic and loaded term in computing. style_classes? Dunno, but not types!

I had originally called the module _styles, but was 'suaded by Tim's argument about it being too close to "style". I would argue that the whole module is private for now so we are free to hash out synonyms to "styles" or "types" for some time before we commit.

I don't see the danger/negative to allowing the user to use the new syntax, even if in this case it's strictly more verbose....

On a technical level that should work. I'm more concerned on "there should only be one way" for the parameters. Are the new classes hidden / mentioned but not emphasized / an equal alternative? For now, I tend towards not mentioning them to the user at all to not increase the perceived API complexity.

You have a point with tab-completion. Unfortunately, jedi will indeed not support string completion from docstrings. However, there's a chance to get string completion from typing at some point davidhalter/jedi#1355.

I'd agree with you, if you hadn't just proposed a new sphinx directive and a new sphinx role. The more of these we have, the more fragile our development process is.

I disagree on fragile. If they are well written and documented, additional roles do not complicate development. In contrast, they can help to generate better, more consistent documentation. E.g. you could auto-generate the possible string values in the HTML docs. Or, if you want explicit values for text docstrings like :mpltype:`joinstyle {'miter', 'round', 'bevel'}` , the role could validate that the stated texts are correct.

On a technical level that should work. I'm more concerned on "there should only be one way" for the parameters.

Hopefully not getting too philosophical here, but while I am always behind have "One Way™" to do things, I don't think allowing the user more options for the type to be passed as a parameter counts as having "more ways". To the contrary, I think it's pretty standard fare---especially in the scientific Python ecosystem---to expect that the input you pass to a function might be converted internally to a more precise representation....I mean even setting numpy aside look at dict_keys or other things even in core Python. From my perspective the etiquette for doing something like this as a library writer seems to be that it's "Okay™" as long as the user doesn't have to know about the internal representation to get the job done (which is still true here).

so I don't know if any users would even blink about it any more than they would be confused whether they are allowed to pass a list or a tuple to certain inputs....

...okay fine so users do get confused about that but I would argue that's just how things are done in Python.

Are the new classes hidden / mentioned but not emphasized / an equal alternative? For now, I tend towards not mentioning them to the user at all to not increase the perceived API complexity.

I don't see any reason reason to mention them, but presumably they will be discovered naturally by users that are reading the documentation deeply anyway, so I don't see any reason to "hide" them either. As long as both the string and enum versions still quack, I don't see users getting upset.

You have a point with tab-completion. Unfortunately, jedi will indeed not support string completion from docstrings. However, there's a chance to get string completion from typing at some point davidhalter/jedi#1355.
How this interacts with Typing is an interesting, but I guess very future discussion, (but IMO having it be a "real" class would greatly simplify any implementation of "types" in the future, even thought we keep the "string" versions forever).

Again, we do this for markers; either take a string or a class, and I don't think its a problem at all, and leaves the door open for users to write new styles. We could do the same for line styles, and that would get us part way towards allowing folks to write their own brush stroke patterns for lines, or complicated dot-dash patterns without ugly strings to parse.

One of the questions influencing the solution space is how we want the docs in rendered and source from to describe these types.

Possible rendered docs:

Possible raw docs:

1) joinstyle : {'miter', 'round', 'bevel'}

2) joinstyle : `JoinStyle`

3) joinstyle : `JoinStyle`-like

4) joinstyle : :mpltype:`{'miter', 'round', 'bevel'}`

5) joinstyle : :mpltype:`JoinStyle`

5b) joinstyle : :mpltype:`JoinStyle {'miter', 'round', 'bevel'}`

6) joinstyle : {'miter', 'round', 'bevel'} or `JoinStyle`

1. is the current way and not what we want as it has no link.
   2)+3) Could be used with type classes and standard numpydoc/sphinx documentation machinery.
   4)+5) Need a custom sphinx role. Due to each of the raw docs could generate either rendered version.
   Raw 4) needs a special internal lookup, that associates "{'miter', 'round', 'bevel'}" with JoinStyle.
2. Is straight forward, but has the drawback that strings cannot be checked/auto-generated.

I'm inclined towards 4). Because it states the string values most users would use both in raw and HTML, but still links to the style docs.

How about:

joinstyle : {'miter', 'round', 'bevel'} or `JoinStyle`

Yes added to the list and scheduled for discussion in the dev call.