Make transformed_data public and add initial docs

[jonmmease]

This is a follow-on to #3081 that makes the new _transformed_data chart methods public and adds an initial documentation section to https://altair-viz.github.io/user_guide/data_transformers.html.

I didn't find an existing sphinx extension to evaluate a Python snippet that doesn't produce an Altair chart, so I added the ipython sphinx directive for this purpose. I'm happy to consider other options if folks have other ideas.

There are probably other places where it would be good to mention this functionality, but this is a starting point. To other maintainers, feel free to commit suggestions directly to this branch, or leave them as review comments.

Thanks!

[binste]

Looks good to me!

[joelostblom]

This looks good to me. I am surprised that an IPython directive is needed to evaluate the code for non-altair output. There are a couple of spaces in the "Specifying data" section where it seems like we show output without using this directive, for example here:

I don't have time to play around with this myself right now, and I'm not against adding more directives to the documentation so I'm happy for this PR to be merged as is, but thought I would just mention the above in case it is helpful.

[jonmmease]

There are a couple of spaces in the "Specifying data" section where it seems like we show output without using this directive

Thanks for calling that out, I'll take a look at how this works and report back.

[jonmmease]

Thanks for calling that out @joelostblom, it works with

.. altair-plot::             
    :output: repr            
                             
    import altair as alt
    ...

I had missed the :output: repr option. ipython directive removed in be59e62

[joelostblom]

Great, merging!