feat: Generate docstrings for mark_ methods

[dangotbanned]

Closes #3262

Description

This PR is a 2-for-1.

1. Primarily Add autogenerated docstrings to mark_ methods #3262
2. But also reduces mixins.py from 3500 to 1600 lines

What I've done here is created a dummy version of each class, where the only difference is the omission of type.
The dummy is used only for the signature & docstring.

If we used core.MarkDef directly, it always displays type first.
I'm assuming that wouldn't be desirable - since we set that explicitly in the method body

Example

IDE

2024-11-04.19-20-41.mp4

API reference

Remains unchanged

[mattijn]

If I recall correctly, not every mark supports the same variable definitions, do you assume here that all marks can use the same MarkDef? Btw, I've no supporting materials yet that supports my assumption.

[dangotbanned]

@mattijn thanks for looking at this so soon!

If I recall correctly, not every mark supports the same variable definitions, do you assume here that all marks can use the same MarkDef? Btw, I've no supporting materials yet that supports my assumption.

Just to be sure I understand what you mean, are you referring to this old comment?

altair/tools/generate_schema_wrapper.py

Lines 920 to 926 in c1e8062

	marks: list[Any] = _def["enum"] if "enum" in _def else [_def["const"]]
	for mark in marks:
	# TODO: only include args relevant to given type?
	mark_method = MARK_METHOD.format(
	decorator=f"_{mark_def}", mark=mark, mark_def=mark_def
	)

I've interpretted that as meaning how the docs for MarkDef has some descriptions which state they only apply for specific marks (e.g. x2 applies to {"area", "bar", "rect", "rule"}).

If so, I don't think there would be a reliable way to do that - since the descriptions aren't written in a consistent style.

---

Or did you mean core.MarkDef vs the composite marks?

altair/altair/vegalite/v5/schema/mixins.py

Line 698 in c1e8062

class _BoxPlotDef(SchemaBase):

altair/altair/vegalite/v5/schema/mixins.py

Line 817 in c1e8062

class _ErrorBarDef(SchemaBase):

altair/altair/vegalite/v5/schema/mixins.py

Line 892 in c1e8062

class _ErrorBandDef(SchemaBase):

If so, then yeah these are split out correctly

[mattijn]

I mean the latter. Good to see that the composite marks are still treated differently, but I thought that not all arguments can be used within the standard marks. It seems that it was and will be covered by just the MarkDef.

[mattijn]

Thanks!

[dangotbanned]

Thanks!

Appreciate the review thanks @mattijn