DOCS: Revamp docs for the 5.0 release #2566

joelostblom · 2022-03-21T19:49:50Z

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:

Things I am still working on:

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. The sidebar ToC is not persistent in the User Guide for some reason, although it works fine on the Getting Started page...
3. The ... action button is far to the right of each chart
4. The project title doesn't align with the logo when the page is made smaller.
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. 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 · 2022-03-22T04:19:02Z

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 · 2022-03-22T08:10:38Z

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 · 2022-03-22T21:09:57Z

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 · 2022-03-23T03:34:46Z

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.

Also move a couple of section inside conf.py

Remove dollar sign for easy copy paste

joelostblom · 2022-03-25T08:38:20Z

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.

joelostblom · 2022-03-25T08:51:15Z

doc/user_guide/interactions.rst

-   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}])


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.

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.

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.

jakevdp · 2022-03-25T17:42:48Z

doc/user_guide/interactions.rst

+
+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.


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

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.

jakevdp

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 · 2022-03-25T18:24:38Z

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

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

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

jakevdp · 2022-03-25T18:31:37Z

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 · 2022-03-25T18:32:12Z

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

mattijn · 2022-03-25T18:32:14Z

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

jakevdp · 2022-03-25T18:34:59Z

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 · 2022-03-25T18:38:13Z

Sounds good, and done per #2578

joelostblom · 2022-03-25T18:47:49Z

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

ChristopherDavisUCI · 2022-03-26T14:30:12Z

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 · 2022-04-04T19:32:24Z

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

joelostblom · 2022-04-15T19:23:50Z

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 · 2022-04-26T20:55:05Z

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 · 2022-06-30T17:40:42Z

Merging as this was already reviewed.

joelostblom force-pushed the docs-revamp-5.0 branch from 49303f1 to 0076f3b Compare March 22, 2022 03:18

joelostblom changed the title ~~Revamp docs for the 5.0 release~~ DOCS: Revamp docs for the 5.0 release Mar 22, 2022

joelostblom force-pushed the docs-revamp-5.0 branch from c8f1ebe to 1bd8b69 Compare March 22, 2022 04:09

joelostblom marked this pull request as ready for review March 22, 2022 04:18

joelostblom requested a review from jakevdp March 22, 2022 04:18

joelostblom force-pushed the docs-revamp-5.0 branch from 1bd8b69 to 753b22c Compare March 22, 2022 20:40

joelostblom added 15 commits March 24, 2022 19:58

Change to sphinx pydata theme

96961c7

Update templates, css, and config for the pydata theme

802e146

Update index structure for the pydata theme

645e5e3

Move case studies and setup redirect

6f0affa

Point to Vega-Lite docs for mark properties

273f6b7

Add headings and reorganize order of sections and headings for clarity

d9d6c59

Remove ToC dropdown error created from empty ToC

9de2dfb

Improve ToC for galleries and move seattle weather to original location

411c950

Do not use rediraffe since it is now not needed

193f7cc

Also move a couple of section inside conf.py

Rename API Reference topbar entry

901320f

Move the ... button next to each chart

c2bff55

Add getting help landing page

4c5093c

Format to pass flake8 tests

0a65172

Make gallery and mini-gallery paths relative so that images show up

42f2905

Compute current copyright year

c1d1b55

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

joelostblom added 2 commits March 24, 2022 23:10

Use recommend way to install via pip

073526f

Remove dollar sign for easy copy paste

Adjust title positioning for narrow screens/windows

27f0789

joelostblom force-pushed the docs-revamp-5.0 branch from 58d4a5a to 10ca002 Compare March 25, 2022 06:10

joelostblom added 2 commits March 24, 2022 23:58

Remove use of deprecated functionality from the documentation

cb197d1

Merge interactions 1 and 2

73238f3

joelostblom force-pushed the docs-revamp-5.0 branch from f52e5a5 to 73238f3 Compare March 25, 2022 08:32

joelostblom commented Mar 25, 2022

View reviewed changes

jakevdp reviewed Mar 25, 2022

View reviewed changes

jakevdp approved these changes Mar 25, 2022

View reviewed changes

mattijn mentioned this pull request Mar 25, 2022

Include documentation for each mark type #2578

Closed

Contrast variable and selection parameters in expression strings

2fe884f

joelostblom added 3 commits April 15, 2022 12:20

Note how to use custom Panel callbacks with Altair selections

1e60804

Add more succinct example of selecting columns from dropdowns

a417d6d

Make examples equivalent

c6eafbc

joelostblom mentioned this pull request Apr 20, 2022

Add interactive gallery via JupyterLite #2593

Draft

joelostblom mentioned this pull request Apr 26, 2022

Make marks to contain subpages and add geoshape docs joelostblom/altair#1

Closed

joelostblom mentioned this pull request Jun 7, 2022

Ensure most Chart methods link to the appropriate class #2610

Closed

Merge branch 'master' into docs-revamp-5.0

a91114e

joelostblom merged commit d966645 into vega:master Jun 30, 2022

joelostblom mentioned this pull request Oct 7, 2022

Geoshape docs revamp 5.0 #2688

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCS: Revamp docs for the 5.0 release #2566

DOCS: Revamp docs for the 5.0 release #2566

joelostblom commented Mar 21, 2022 •

edited

Loading

joelostblom commented Mar 22, 2022

mattijn commented Mar 22, 2022

joelostblom commented Mar 22, 2022

joelostblom commented Mar 23, 2022

joelostblom commented Mar 25, 2022

joelostblom Mar 25, 2022

jakevdp Mar 25, 2022

joelostblom Mar 25, 2022 •

edited

Loading

joelostblom Mar 25, 2022

jakevdp Mar 25, 2022

joelostblom Mar 25, 2022

jakevdp left a comment

joelostblom commented Mar 25, 2022

jakevdp commented Mar 25, 2022

jakevdp commented Mar 25, 2022

mattijn commented Mar 25, 2022

jakevdp commented Mar 25, 2022 •

edited

Loading

mattijn commented Mar 25, 2022

joelostblom commented Mar 25, 2022

ChristopherDavisUCI commented Mar 26, 2022

joelostblom commented Apr 4, 2022

joelostblom commented Apr 15, 2022

mattijn commented Apr 26, 2022

joelostblom commented Jun 30, 2022


		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.

DOCS: Revamp docs for the 5.0 release #2566

DOCS: Revamp docs for the 5.0 release #2566

Conversation

joelostblom commented Mar 21, 2022 • edited Loading

joelostblom commented Mar 22, 2022

mattijn commented Mar 22, 2022

joelostblom commented Mar 22, 2022

joelostblom commented Mar 23, 2022

joelostblom commented Mar 25, 2022

joelostblom Mar 25, 2022

Choose a reason for hiding this comment

jakevdp Mar 25, 2022

Choose a reason for hiding this comment

joelostblom Mar 25, 2022 • edited Loading

Choose a reason for hiding this comment

joelostblom Mar 25, 2022

Choose a reason for hiding this comment

jakevdp Mar 25, 2022

Choose a reason for hiding this comment

joelostblom Mar 25, 2022

Choose a reason for hiding this comment

jakevdp left a comment

Choose a reason for hiding this comment

joelostblom commented Mar 25, 2022

jakevdp commented Mar 25, 2022

jakevdp commented Mar 25, 2022

mattijn commented Mar 25, 2022

jakevdp commented Mar 25, 2022 • edited Loading

mattijn commented Mar 25, 2022

joelostblom commented Mar 25, 2022

ChristopherDavisUCI commented Mar 26, 2022

joelostblom commented Apr 4, 2022

joelostblom commented Apr 15, 2022

mattijn commented Apr 26, 2022

joelostblom commented Jun 30, 2022

joelostblom commented Mar 21, 2022 •

edited

Loading

joelostblom Mar 25, 2022 •

edited

Loading

jakevdp commented Mar 25, 2022 •

edited

Loading