Include documentation for each mark type

[mattijn]

The docs for marks are currently still missing in the Altair documentation. It would be nice to have a similar structure as the Data Transformations for Marks.

Raised before in #2566 (comment)

[hebarton5]

Moving conversation from #2580 here! I would be willing to contribute to documentation on each mark, especially now that you have provided and example with mark_geoshape(). Since each mark already has a tagged example associated with it, what additional information/examples should be included in the documentation?

[joelostblom]

Hello @hebarton5 ! Thank you so much for your interest in contributing to Altair. I think it would be really nice to follow the design of the Mark page in Vega-Lite when building it for Altair. I also like the reorganization that @mattijn started in joelostblom#1 (preview) so we can draw inspiration from there as well. Here is what I would suggest (1 and 2 are the most important, and I'm open to feedback):

1. I think the landing page should include a short intro to what marks are (similar to what is there now already), the table of all available marks (same format as in @mattijn PR), and then a heading "Mark Properties" which contains the current mark properties table, but divided into subheadings as can be seen on the VegaLite page (general, position and offset, color, stroke style, and finally hyperlink properties) (i don't think the last "style" section is as important).
2. I like the format of individual mark pages being subpages under the "Mark" headings (as in @mattijn 's PR) rather than links to the gallery. Let's include a few examples for each mark directly on the page, ideally translating the ones showed at the Vega-Lite pages to Altair code (+ mentioning any differences in Altair where appropriate, I can help with that part). Some of these are relative brief, e.g. the arc examples whereas others are really long, e.g. the boxplot example. Feel free to shorten the really long pages (e.g. we don't need to talk about "The Parts of Box Plots") and only include a few examples to start with (we can always add more later).
3. I find it really helpful that VegaLite includes a table on each mark subpage of all the properties specific to each mark. It would be great if we could have this in Altair too (currently we only have one big table for all marks that is hard to navigate).
   • The challenge here will be to pull this information automatically because we don't want to update it manually each time there is a Vega-Lite update (this would probably also lead to errors). You could explore pulling this info either from the VegaLite repo directly as part of the docs make file, or (preferably) if we could somehow populate this table via sphinx inspecting that arguments taken by each alt.Chart().mark_*.
   • Another alternative is to manually filter the properties from MarkDef to only include the relevant ones; this way all the descriptions will still be automatic so that could work as well and is similar to how they do it in VegaLite. (explained a bit in the contrib guidelines)
4. You will also notice that the individual mark subpages in the VegaLite documentation has a really helpful section with sliders where you can interact with and see how it impacts the chart visuals. I am not sure we will be able to add something like this, but one approach could be to pull the Vega-Lite specs from those URLs and display them in the Altair docs as well (either via Altair's VegaLite primitives or directly in the HTML).
   • This is what I mean with a primitive, aka using the VegaLite spec from their docs directly:

     from altair import VegaLite;
     
     VegaLite({"data": {"values": [{"amount": 28, "category": "A"}, {"amount": 55, "category": "B"}]}, "encoding": {"x": {"field": "category"}, "y": {"field": "amount", "type": "quantitative"}}, "mark": "bar"})

Ok that was a lot of text, as I mentioned, I think 1 and 2 are the most important items here. Does it feel doable to get started with those? Feel free to ask any questions you have here in this issue! Work from the code in https://github.com/joelostblom/altair/tree/docs-revamp-5.0 until #2566 is merged.

[hebarton5]

I think this is a good place to start!