Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCS: Revamp docs for the 5.0 release #2566

Merged
merged 24 commits into from
Jun 30, 2022

Conversation

joelostblom
Copy link
Contributor

@joelostblom joelostblom commented Mar 21, 2022

This is a suggestion for what the Altair docs could look like based on the discussion in #1994. I tried to bring the aesthetics a bit closer to the appearance of the docs for other Python data science libraries and Vega-Lite.

You can browse the documentation here https://joelostblom.github.io/altair-docs/index.html.

I think it would be good to merge #2415 before this PR, so that I can take into account those new doc sections, but I can also do that later if we want to merge this first. I hope to write some more doc pages, such as working with images, geodata, and more tutorials/case studies at some point later this year.

Screenshot of the front page:
image

Things I am still working on:

  1. 1. The organization of the user guide. I currently included "Advanced Usage", but moved "Case Studies" and "Getting Help" to the topbar, very open to feedback. I am happy with my current suggestion, but still open to feedback!
  2. 2. The sidebar ToC is not persistent in the User Guide for some reason, although it works fine on the Getting Started page...
  3. 3. The ... action button is far to the right of each chart
  4. 4. The project title doesn't align with the logo when the page is made smaller.
  5. 5. The gallery thumbnails didn't show up initially (maybe the same issue as Error compiling docs for v4.1.0 tag #2092). I fixed this in 1bd8b69 by making the paths relative, but if someone else can confirm that this works for the way the documentation is built before being put on altair-viz.github.io that would be great.
  6. 6. Headings don't show up in the gallery

Please have a look at the page and add additional things you see that are broken or could be improved.

Note that I have removed the gallery items from their toc trees to better display the examples page and not clutter its ToC. This raises warnings during the sphinx build but they still show up fine and are easy to navigate via the right hand headings menu. There is also a warning about using the same "Vega-Lite" target for different links, but everything works as expected.

@mattijn Regarding your comment on reorganization and breaking existing links across the web: For now I only moved one page, the Seattle weather case studies, and used the sphinx extension rediraffe to redirect the old link (https://joelostblom.github.io/altair-docs/case_studies/exploring-weather.html) to https://joelostblom.github.io/altair-docs/user_guide/case_studies/exploring-weather.html. Edit: I returned this page to its original location for other reasons, but rediraffe seems to work so it could be an option if we want to reorganize.

close #1994

@joelostblom joelostblom changed the title Revamp docs for the 5.0 release DOCS: Revamp docs for the 5.0 release Mar 22, 2022
@joelostblom joelostblom marked this pull request as ready for review March 22, 2022 04:18
@joelostblom
Copy link
Contributor Author

I was able to iron out most of the issues I had initially and all checks are green now, so I am marking this as ready for review.

@mattijn
Copy link
Contributor

mattijn commented Mar 22, 2022

Truly awesome @joelostblom! Love it. It is amazing that one can change the whole look and feel, but keeping all URLs functional. I like it a lot!

Your change regarding the table in https://github.com/altair-viz/altair/pull/2566/files#diff-24d8b87040ed30683fe42c11038ae58c012c813146a101f0c177cca2a7c9d626R20-R33 to include references to documentation to the properties of each mark make sense. Currently you refer to the VL-repo, but this can be a nice open issue for someone to make the Altair counterparts.

@joelostblom
Copy link
Contributor Author

Thanks @mattijn! I am happy to hear that you like it =) I agree that is someone want to make the Altair counterparts for those sections we can link to them instead in the future. Although I also think that it is nice with some links to the Vega-Lite docs here and there to remind folks to study those as well before asking questions.

@joelostblom
Copy link
Contributor Author

I rebased on the main branch so that all the tests pass. I also checked off the last items that I was working on above, so there is nothing more I am planning to add here.

@joelostblom joelostblom force-pushed the docs-revamp-5.0 branch 2 times, most recently from 27f7ec7 to 58d4a5a Compare March 25, 2022 06:08
@joelostblom
Copy link
Contributor Author

I made a couple of more updated since the VL5.2 PR was merged. This is now rebased on master and I updated the docs to remove references to the old VL4 syntax. I also merged the chapters on interaction 1 and 2 since together they had a lot of overlap and tried to make it into a single narrative about interactions.

I also updated all the examples, but put that in #2576 so that it is easier to merge them since they are part of the test suite. I don't think there is anything more to add now as long as all the tests pass. I think it would be neat to have a doc page about geo viz and images, but that will be a future PR.

selector = alt.selection_single(name="SelectorName", fields=['cutoff'],
bind=slider, init={'cutoff': 50})
selector = alt.selection_point(name="SelectorName", fields=['cutoff'],
bind=slider, value=[{'cutoff': 50}])
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure that we need this example anymore since it is easier to do this with parameter variables now (selector = alt.parameter(value=50, bind=slider). But maybe it is good to show both next to each other, we could also move it higher up closer to / in the parametervariable section.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed - I don't think we would have added this example if variables had been available! Can you think of any reasons we might want to use this selection name lookup now that parameter variables are a thing? If not, I'd say we can remove this example.

Copy link
Contributor Author

@joelostblom joelostblom Mar 25, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I remember I thought it was useful to learn that we could access the fields of parameters (as with selector.cutoff in that example), but I am not sure if that is useful anywhere else now. Maybe what I will do is to include it higher up as an example of some of the power introduced with variable in contrast to how we had to use selections before. I will ping when I have updated it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!


Some possible use cases for the above interactivity are not currently supported by Vega-Lite, and hence are not currently supported by Altair. Here are some examples.

1. If we are using a ``selection_point``, it would be natural to want to return information about the chosen data point, and then process that information using Python. This is not currently possible (and as of December 2021 it does not seem likely to become possible any time soon), so any data processing will have to be handled using tools such as ``transform_calculate``, etc. You can follow the progress on this in the following issue: https://github.com/altair-viz/altair/issues/1153.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we mention that streamlit has some tools for this kind of thing?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this was never implemented in streamlit and only the proof of principle that domoritz created exists as of now. It is possible in the master branch of panel as mentioned here, but they have not had a release yet. I am planning to write something short about integrating with dashboard solutions building on my answer here and will make sure to include this when there is a new release.

Copy link
Collaborator

@jakevdp jakevdp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks really great, thanks for tackling this! One question - should we link to the Altair Mark properties page rather than the vega-lite versions? I worry that the latter links might go stale if Vega-Lite continues evolving and releasing at a faster clip than Altair.

@joelostblom
Copy link
Contributor Author

Thank you! The reason I am linking to the Vega-Lite page is the interactive controls they have added which make it really easy to explore the effect of varying parameter on the chart. My vote would be to keep this until someone implements the corresponding pages with interactive controls in the Altair docs as mattijn suggested.

For example, linking to https://vega.github.io/vega-lite/docs/arc.html#properties

image

seems more useful than linking to https://joelostblom.github.io/altair-docs/user_guide/generated/core/altair.Mark.html

image

Or is there another doc page for Altair marks that I have missed?

@jakevdp
Copy link
Collaborator

jakevdp commented Mar 25, 2022

No, I don't think we have anything like that on the Altair docs. But maybe we could with the new parameters framework?

Linking to Vega-Lite for now is fine.

@jakevdp
Copy link
Collaborator

jakevdp commented Mar 25, 2022

Are you ready to merge this? It's a great improvement!

@mattijn
Copy link
Contributor

mattijn commented Mar 25, 2022

No you did not miss pages, but I would vote to include a similar structure as the Data Transformations for Marks.

@jakevdp
Copy link
Collaborator

jakevdp commented Mar 25, 2022

No you did not miss pages, but I would vote to include a similar structure as the Data Transformations for Marks.

+1, that would be a really nice way to approach those. Maybe merge this in its current state and open another issue to track that?

@mattijn
Copy link
Contributor

mattijn commented Mar 25, 2022

Sounds good, and done per #2578

@joelostblom
Copy link
Contributor Author

@jakevdp Yes ready to merge! I just addressed your comment in my latest commit.

@ChristopherDavisUCI
Copy link
Contributor

I hadn't noticed all this activity or that the docs were actually browsable... this all looks awesome and I'm amazed at how (seemingly) quickly it all came together! Thanks @joelostblom!!

@joelostblom
Copy link
Contributor Author

@jakevdp Just a reminder that this is ready to merge! (and let me know if you prefer not to be pinged like this)

@joelostblom
Copy link
Contributor Author

Panel just released their version 0.13 which supports custom callbacks on Altair selections, so I added a link to their docs. I also added the example from #2579 (comment) to show another use case for parameters

@mattijn
Copy link
Contributor

mattijn commented Apr 26, 2022

I did a PR on the branch of @joelostblom as this is not yet merged. Not sure if that is a good idea. Do we like to merge this PR first in its current condition and continue with PRs on the main repo of altair or extend this branch https://github.com/joelostblom/altair/tree/docs-revamp-5.0?

@joelostblom
Copy link
Contributor Author

Merging as this was already reviewed.

@joelostblom joelostblom merged commit d966645 into vega:master Jun 30, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Upgrade Altair documentation page
4 participants