Restructure and clarify interactive docs #2981
Conversation
…arisons more clearly and change search example
|
I think I finally found a sensible way to organize the widget section in my last commit! |
There was a problem hiding this comment.
Great improvements @joelostblom! I left a few comments in-line.
doc/user_guide/interactions.rst
Outdated
|
|
||
| Interactivity in Altair is built around *parameters*, of which there are two types: *variables* and *selections*. We introduce these concepts through a series examples. | ||
| Parameters are the building blocks of interaction in Altair. | ||
| There are two types of parameters: *variables* (the :func:`param` function) and *selections* (the :func:`selection` function). We introduce these concepts through a series examples. |
There was a problem hiding this comment.
It feels a bit strange to refer to selections since we just deprecate this function. Maybe better to not refer by a hyperlink? Or refer to selection_point, selection_interval. There is also a potential upcoming selection_region, so maybe not a good idea to mention all of them?
There was a problem hiding this comment.
Agree and updated
doc/user_guide/interactions.rst
Outdated
| @@ -263,8 +240,49 @@ We can modify the brush definition, and leave the rest of the code unchanged: | |||
|
|
|||
| chart.encode(x='Acceleration:Q') | chart.encode(x='Miles_per_Gallon:Q') | |||
There was a problem hiding this comment.
| chart.encode(x='Acceleration:Q') | chart.encode(x='Miles_per_Gallon:Q') | |
| chart.encode(x='Horsepower:Q') | chart.encode(x='Displacement:Q') |
I think we should keep Horsepower consistently on the x channel, in line with getting-started/overview page. And also start with the Miles_Per_Gallon/Horsepower on the left-chart and append another one on the right. I don't see much variation between the columns Accelaration and Miles_Per_Gallon, maybe better to use Displacement? (I've no feeling with the meaning of these column-names btw..)
If you agree, than we should apply this suggestion across all examples on this pages I think.
There was a problem hiding this comment.
I agree with this and updated the examples on the page
| input_dropdown = alt.binding_radio( | ||
| # Add the empty selection which shows all when clicked | ||
| options=options + [None], | ||
| labels=labels + ['All'], |
There was a problem hiding this comment.
# Make radio button less cramped by adding a space after each label
options = ['Europe', 'Japan', 'USA']
labels = [option + ' ' for option in options]
I'm not sure if this spacing works. This is what I see as a result:
There was a problem hiding this comment.
Yes, the spacing does not work in the docs, but they do work in a jupyter notebook... I am meaning to fix the CSS in vegalite long term and then we can remove this. For now I added a note. ref vega/vega-lite#8799 (comment)
doc/user_guide/interactions.rst
Outdated
| For example, | ||
| we might want to create a condition | ||
| where we want to access the value of a slider | ||
| to use directly in a comparison with values of the data. |
There was a problem hiding this comment.
For example,
we might want to create a condition
where we want to access the value of a slider
to use directly in a comparison with values of the data.
It is a bit hard for me to understand this sentence, especially the last part. After reading it two times I get what you mean. Maybe split in two sentences?
Co-authored-by: Mattijn van Hoek <mattijn@gmail.com>
| input_dropdown = alt.binding_radio( | ||
| # Add the empty selection which shows all when clicked | ||
| options=options + [None], | ||
| labels=labels + ['All'], |
There was a problem hiding this comment.
Yes, the spacing does not work in the docs, but they do work in a jupyter notebook... I am meaning to fix the CSS in vegalite long term and then we can remove this. For now I added a note. ref vega/vega-lite#8799 (comment)
doc/user_guide/interactions.rst
Outdated
|
|
||
| Interactivity in Altair is built around *parameters*, of which there are two types: *variables* and *selections*. We introduce these concepts through a series examples. | ||
| Parameters are the building blocks of interaction in Altair. | ||
| There are two types of parameters: *variables* (the :func:`param` function) and *selections* (the :func:`selection` function). We introduce these concepts through a series examples. |
There was a problem hiding this comment.
Agree and updated
doc/user_guide/interactions.rst
Outdated
| For example, | ||
| we might want to create a condition | ||
| where we want to access the value of a slider | ||
| to use directly in a comparison with values of the data. |
doc/user_guide/interactions.rst
Outdated
| @@ -263,8 +240,49 @@ We can modify the brush definition, and leave the rest of the code unchanged: | |||
|
|
|||
| chart.encode(x='Acceleration:Q') | chart.encode(x='Miles_per_Gallon:Q') | |||
There was a problem hiding this comment.
I agree with this and updated the examples on the page
Co-authored-by: Mattijn van Hoek <mattijn@gmail.com>
|
Great! I accepted all your suggestions. Merging. |
As I was adding the new interactive examples from #2760, I noticed several things I think we could express more clearly so I went through and overhauled this page. It is mostly clarification, and making titles a bit more succinct so that they are easier to get an overview from. I also restructured some sections mostly the widget one to try to give a more structured walk-through of the different options (I'm open to ideas if anyone thinks my suggestion could be improved).
Docs are live here so that it is easier to review https://joelostblom.github.io/altair-docs/user_guide/interactions.html#
Before:
After:
