Upgrade Altair documentation page

[mattijn]

The more I use Altair the more I found myself lost in the documentation page. Something that I don't feel when I'm on the doc page on the Vega-lite side.

I almost don't dare to say it, but with the continuous growth of possibilities and users, maybe its time to redo the doc page to get it more aligned with the Vega-lite side..

[jakevdp]

Sure, what suggestions do you have?

[mattijn]

Eventually I'm able to find the information I need, but currently its a bit hidden in the closed directory structure on the left.

I wish to have a vertical bar on the top to go to specific parts in the documentation. Something like the current Vega-Lite or Pandas docs.

This will split the amount of information in the current directory structure significantly.

In the Vega-Lite docs I like the clear minimalistic categorisation of options under Transform, Mark, Encoding, View composition and Selections. Especially the inclusion of the various mark types, which is very much the core of any visualisation.

By the way, in the docs of Vega-Lite there are no options under Data / Datasets:

I think there should be some sub-options, especially for Altair.

Furthermore I won't deny that the adopted font size and usage of white gives a pleasant reading experience in the Vega-Lite docs (vs both Pandas and Altair docs).

[jakevdp]

Great! The source is in docs and a lot of the Altair-specific sphinx functionality is in altair/sphinxext. Give it a whirl and see if you can come up with some tweaks that will bring it closer to how you wish it was.

I won't lie though: fine-tuning sphinx themes is not easy or fun.

[mattijn]

How fixed are you on sphinx? Will the fun(potential contributors) increase when using Jekyll / markdown?

[jakevdp]

I chose sphinx because it provides the ability to do auto-documentation based on Python docstrings, and makes it easy to define custom directives (for things like embedding Altair plots and generating the gallery)

I wouldn't be opposed to moving to another system if that would be easier to maintain and update.

[mattijn]

Ok, thanks for prompt response. I'm not jumping directly on this issue, but at least some info is documented here.

[mattijn]

I adopted the pydata-sphinx-theme and made a few changes in the organisation of files and the result is already very clean.

See following animated gif:

By including nbsphinx as extension we can organise most of the documentation-pages as notebooks (like Jupyter book).

Progress at least!

[jakevdp]

Awesome! That would be really great.

Regarding nbsphinx... I recently transitioned another project from nbsphinx to myst-nb, and I'm finding the latter to be a much cleaner way to integrate notebooks into sphinx docs.

[joelostblom]

@mattijn Is it ok if I look into updating the docs for 5.0 or do you have some specific changes you want to make that are already in progress? I am thinking of doing something very similar as what you suggest here with changing the theme to look more like the Vega docs and I am curious to what reorganization you had in mind. I don't think I will switch the docs over to notebooks for the time being, but I agree that jupyter books with myst is a very nice way to work with documentation in general and what I use for new projects myself.

[mattijn]

Sure, go ahead! I had a try with the suggestions above at that time. At that moment I struggled a bit with (1) apply a new theme while maintaining the url-references on the internet still point to the right page, or (2) restructure the documentation and accept that references elsewhere on the internet needs to be updated.

I tried 1, but if you improve the structure significantly, just do 2.

[mattijn]

You were able to make any progress on this @joelostblom?

[joelostblom]

Nope, I got caught up in too many things at work. I'm planning to revisit when I have more time, but probably not until late Feb so feel free to work on this if you have time and think 5.0 will be out before I get back on this.

[mattijn]

No problem. Lets see, good to know👍