Altair: DOC: improvements checklist

[jakevdp]

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.

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

[f0lie]

I am a bit confused on how to add documentation. Is there some sort of workflow guide for the documentation? Also standards and tips?

[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!

[f0lie]

So I tried to follow your instructions and it turns out it's a bit more complicated.

Here's the instructions for a MacOS. It actually doesn't work but it's most of the way there.

$ git clone https://github.com/altair-viz/altair
$ brew cask install chromedriver
$ cd altair
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install -r requirements.txt -r requirements_dev.txt -r doc/requirements.txt
$ cd doc
$ make html

I get a selenium error selenium.common.exceptions.JavascriptException: Message: javascript error: vl is not defined. Googling doesn't get me anything useful.

[jakevdp]

vl here is the vega-lite library, which is loaded from the web by selenium. Is it possible that your selenium engine is somehow being blocked from accessing the internet?

[jakevdp]

(also, FYI the only thing selenium is used for here is generating thumbnails for the example gallery. You may be able to build the rest of the site without it)

[f0lie]

I am working in an corporate environment so it's probably blocked. How do I build without selenium? I am just trying to see the graphs that are produced.

[jakevdp]

Hmm... I don't think there's any built-in way to avoid it at the moment, but you could probably comment-out this line to do it: https://github.com/altair-viz/altair/blob/88ec1e01188f4c46d4d686522ca3fc1a881339f3/altair/sphinxext/altairgallery.py#L129

A better solution long-term might be to add logic to catch errors in that line and save a blank place-holder image instead, so that docs could be built without example thumbnails.

[f0lie]

  File "/Users/user/altair/venv/lib/python3.7/site-packages/PIL/Image.py", line 2580, in open
    fp = builtins.open(filename, "rb")
FileNotFoundError: [Errno 2] No such file or directory: '/Users/user/altair/doc/_images/anscombe_plot.png'

Still getting an error, looks like something somewhere expects the file to be written.

[jakevdp]

Right, you'll have to create a stand-in image somehow.

[f0lie]

Maybe I could just figure out how to make selenium use the proxy?

[jakevdp]

Here's a PR that uses a stand-in thumbnail when selenium is not available: #1066

Note, it depends on catching an ImportError so it's best to use this with selenium not installed.

[jimmywan]

Any chance that we could add an example for blending map data with a dataframe containing WGS84 coordinates already in it?

This was a snippet from my admittedly extremely naive attempt at just slapping a backing US map on a scatter plot using longitude/latitude as X/Y:

counties = alt.topo_feature(data.us_10m.url, 'counties')
background = alt.Chart(counties).mark_geoshape(
    fill='#666666',
    stroke='white'
).encode(
).project(
    type='equirectangular'
)

background + chart

[jakevdp]

You should be able to use the latitude and longitude encodings, like in this example: https://altair-viz.github.io/gallery/airports.html

[kindofluke]

I just opened a PR for adding documentation on Sort to the user guide.

[kindofluke]

@jakevdp just started on binding. You can feel free to take a look in the branch binding-documentation

this has been my approach:

• [x] With adding input elements and bindings the page should just be called interactions.
• [x] Add simple dropdown example
• [x] add an example using filter
• [x] enumerate all of the avail input elements.
• [x] bind to "scales" magic for panning and zooming
• [ ] headers are all out of wack
• [ ] spelling and proofread

[jakevdp]

@kindofluke this looks great! Feel free to open a pull request even if it's still a work in progress – it makes it easier to track commits and see diffs.

[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