DOC: improvements checklist

There have been a number of questions from users that point to weaknesses in our docs. This issue is an attempt to compile them into a checklist.

• sort order for legends, columns, etc. (#1059, addressed in #1069)
• Controlling rangeStep for ordinal charts (#1050, fixed in #1076)
• Confusing type syntax in API docs (#1051)
• Selections: use of encodings and fields (#1049, fixed in #1080)
• Advanced section with more detailed discussion of connection between Altair API, Altair object structure, and Vega-Lite schema structure. (Done in #1062)
• Examples of local vs UTC time & warnings about formatting for dates-as-strings (#1027, addressed in #1087)
• More examples of bindings, sliders, etc. (done in #1113)
• hiding grids, axes, borders (#1009)
• fix discussion of data specification in compound charts (#1079)
• add discussion of data in indices and reset_index() (#1079)
• Add information about data_transformers.consolidate_datasets (done in #1081)
• fix sphinx errors (many undefined/duplicate names, etc.) (Done in #1063)
• clean up API docs (done in #1063)

[jakevdp]

@adiep2501 thanks for your interest – no, there’s no guide at the moment (I should add that to the checklist!)

The basics are this:

• the source of the documentation is in the doc subdirectory
• You can edit the RST source (for example, encoding.rst) which will be processed using sphinx to convert it to HTML (for example, encoding.html).

If you make any significant changes, it helps to render the docs locally to check that everything is working, which you can do by running make html within the doc directory (this requires you install all the packages in doc/requirements.txt)

I hope that’s clear!

[jakevdp]

Aside from the type syntax, we’ve checked all the boxes now! As it’s not clear how that last one will be solved, I’m going to go ahead and close this issue