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.

• sort order for legends, columns, etc. (ordering of legend labels #1059, addressed in Documentation of Sorting Columns and Legends #1069)
• Controlling rangeStep for ordinal charts (Bar graph width overlapping with size parameter #1050, fixed in Docs regarding width of bar marks #1076)
• Confusing type syntax in API docs ("anyOf" syntax in API documentation is too techie and difficult for n00bs  #1051)
• Selections: use of encodings and fields (Unable to use interval selection on all points of a line chart #1049, fixed in DOC: add documentation of fields and encodings in selections #1080)
• Advanced section with more detailed discussion of connection between Altair API, Altair object structure, and Vega-Lite schema structure. (Done in DOC: add documentation of internal details + some doc cleanup #1062)
• Examples of local vs UTC time & warnings about formatting for dates-as-strings (Monthly data and ordinal encoding create an "off by one" error #1027, addressed in DOC: add discussion of dates & times in Altair #1087)
• More examples of bindings, sliders, etc. (done in Binding documentation #1113)
• hiding grids, axes, borders (DOC: Example of hiding the border using configure_view. #1009)
• fix discussion of data specification in compound charts (DOC: add discussion of index data #1079)
• add discussion of data in indices and reset_index() (DOC: add discussion of index data #1079)
• Add information about data_transformers.consolidate_datasets (done in DOC: add discussion of consolidate_datasets #1081)
• fix sphinx errors (many undefined/duplicate names, etc.) (Done in DOC: use autosummary to clean up API docs #1063)
• clean up API docs (done in DOC: use autosummary to clean up API docs #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:

• With adding input elements and bindings the page should just be called interactions.
• Add simple dropdown example
• add an example using filter
• enumerate all of the avail input elements.
• 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