Documentation for each mark type #2607
Conversation
|
🎉👍 |
There was a problem hiding this comment.
This is looking great @hebarton5! Thank you so much again for contributing to the Altair docs. And I am sorry for my slow review here, I was away for a few days and got busy at work when I returned. I added some comments on the index page and the first few mark pages. If you can reply to these and add the remaining marks to the page index, I will be able to review the rest.
| ========================================= ========================================= ================================================================================ | ||
| :ref:`user-guide-arc-marks` :meth:`~Chart.mark_arc` A pie chart. | ||
| :ref:`user-guide-area-marks` :meth:`~Chart.mark_area` A filled area plot. | ||
| bar :meth:`~Chart.mark_bar` A bar plot. |
There was a problem hiding this comment.
I like linking the pages here as you have done for the arc and area mark. Could you do the same for the remaining marks?
| :hidden: | ||
|
|
||
| arc | ||
| area |
There was a problem hiding this comment.
Include all the marks here as well so that they show up in the navigation menu. Ping me once you have done this and I will rebuilt the docs and review all the marks after "Area" as well.
| Area Config | ||
| ^^^^^^^^^^^ | ||
| The ``arc`` property of the top-level ``config`` object sets the default properties for all arc marks. If mark property encoding channels are specified for marks, these config values will be overridden. | ||
|
|
||
| The area config can contain any area mark properties (except ``type``, ``style``, and ``clip``). |
There was a problem hiding this comment.
Could you remove this config section for each of the marks? I don't think it adds anything of value to the Altair side of things; it is more relevant for the VegaLite specs.
| Arc marks are circular arcs defined by a center point plus angular and radial extents. | ||
| Arc marks are typically used for radial plots such as pie and donut charts. | ||
|
|
||
| Examples |
There was a problem hiding this comment.
Were you able to explore whether it is possible to add the "Properties" table for each mark page? Like in https://vega.github.io/vega-lite/docs/arc.html#properties and point 3 of #2578 (comment)
| As seen in the last two examples, additional arguments to ``mark_*()`` methods are passed along to an | ||
| associated :class:`MarkDef` instance, which supports the following attributes: | ||
|
|
||
| .. altair-object-table:: altair.MarkDef |
There was a problem hiding this comment.
Is it possible to divide this table into subsections as in https://vega.github.io/vega-lite/docs/mark.html#mark-def? "General", "Color", etc.
| Instead of using a single color as the fill color of the area, we can set it to a gradient. | ||
| In this example, we are also customizing the overlay. For more information about gradient options see the Vega-Lite Gradient documentation. | ||
|
|
||
| .. altair-plot.:: |
There was a problem hiding this comment.
There is an additional . before the :: that prevents this chart from showing up in the built docs
| ) | ||
|
|
||
| Instead of using a single color as the fill color of the area, we can set it to a gradient. | ||
| In this example, we are also customizing the overlay. For more information about gradient options see the Vega-Lite Gradient documentation. |
There was a problem hiding this comment.
Could you link to https://vega.github.io/vega-lite/docs/gradient.html?
| Ranged Area | ||
| ^^^^^^^^^^^ | ||
| Specifying ``x2`` or ``y2`` for the quantitative axis of area marks produce ranged areas. For example, we can use ranged area with the ``ci0`` and ``ci0`` | ||
| aggregation operators to highlight 95% confidence interval of a line chart that shows mean values over time. |
There was a problem hiding this comment.
Could you link to this page for the available aggregation operators? user_guide/encoding.html#binning-and-aggregation
| ^^^^^^^^^^^ | ||
|
|
||
| We can also shift the stacked area chart’s baseline to center and produces a streamgraph by setting ``"stack"`` to ``"center"`` in the encoding channel. | ||
| Adding the ``interactive`` method allows for changing the scales. |
There was a problem hiding this comment.
| Adding the ``interactive`` method allows for changing the scales. | |
| Adding the ``interactive`` method allows for zooming and panning the x-scale. |
|
@hebarton5 Just checking in on this, would you be interested in working on addressing the comments I made? |
|
Or merge and accept as being "infrastructure code" and iterate further? I think this has been work part of an (given?) assignment. |
|
Yeah, that makes sense, I won't have time to iterate on it for a while myself so maybe we should merge this when one of us have time to rewrite it so that these doc pages are not broken on the main branch? |
|
Make sense, first fix conflicts before merging. |
|
@joelostblom I probably find some time during the next 4-5 weeks to address the open comments in this PR. However, I don't think I can edit this PR directly right? Could you merge it first or is there a better approach? |
|
I fixed the conflict. @binste, from here you can create a new PR to work on the review from @joelostblom. Thank you for for offering help. |
This PR includes subpages for each mark. All content is based off of the vega-lite mark documentation (https://vega.github.io/vega-lite/docs/mark.html), with adjustments made to make it applicable to Altair.