DOC: improvements checklist

jakevdp commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

@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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

(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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

  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 commented 6 years ago

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

f0lie commented 6 years ago

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

jakevdp commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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

kindofluke commented 6 years ago

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

kindofluke commented 6 years ago

@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 commented 6 years ago

@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 commented 6 years ago

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

vega / altair

DOC: improvements checklist #1060