[Doc] Update UserGuide: Add Rotate Axis, Sort Legend Example, Citing …

…Section (#3217)

* [Doc] Update UserGuide: Add Rotate Axis Method

* [Doc] Update User Guide: Add sort legend using EncodingSortField example

* [Doc] Ａｄｄ　Ｃｉｔｉｎｇ　Ｓｅｃｔｉｏｎ　

* Add Citing Section

* Update to new sorting without explicit encoding field and fix a few small typos

* Avoid configure_axis method and use .axis() directly

Co-authored-by: Joel Ostblom <[email protected]>

* Fix parenthesis

* Clarify text

---------

Co-authored-by: Rita Weng <[email protected]>
Co-authored-by: Joel Ostblom <[email protected]>
Co-authored-by: Joel Ostblom <[email protected]>

doc/about/citing.rst

@@ -0,0 +1,41 @@
+Citing
+===============
+
+Vega-Altair
+-----------
+If you use Vega-Altair in academic work, please consider citing
+`Altair: Interactive Statistical Visualizations for Python <https://joss.theoj.org/papers/10.21105/joss.01057>`_ as
+
+.. code-block::
+
+  @article{VanderPlas2018,
+    doi = {10.21105/joss.01057},
+    url = {https://doi.org/10.21105/joss.01057},
+    year = {2018},
+    publisher = {The Open Journal},
+    volume = {3},
+    number = {32},
+    pages = {1057},
+    author = {Jacob VanderPlas and Brian Granger and Jeffrey Heer and Dominik Moritz and Kanit Wongsuphasawat and Arvind Satyanarayan and Eitan Lees and Ilia Timofeev and Ben Welsh and Scott Sievert},
+    title = {Altair: Interactive Statistical Visualizations for Python},
+    journal = {Journal of Open Source Software}
+  }
+
+Vega-Lite
+---------
+Please additionally consider citing the
+`Vega-Lite <https://vega.github.io/vega-lite/>`_ project, which Vega-Altair is based on:
+`Vega-Lite: A Grammar of Interactive Graphics <https://dl.acm.org/doi/10.1109/TVCG.2016.2599030>`_
+
+.. code-block::
+
+  @article{Satyanarayan2017,
+    author={Satyanarayan, Arvind and Moritz, Dominik and Wongsuphasawat, Kanit and Heer, Jeffrey},
+    title={Vega-Lite: A Grammar of Interactive Graphics},
+    journal={IEEE transactions on visualization and computer graphics},
+    year={2017},
+    volume={23},
+    number={1},
+    pages={341-350},
+    publisher={IEEE}
+  }

doc/about/roadmap.rst

@@ -162,3 +162,4 @@ Areas of focus:
    self
    code_of_conduct
    governance
+   citing

doc/user_guide/customization.rst

@@ -294,7 +294,7 @@ the y labels as a dollar value:
        alt.Y('y').axis(format='$').title('dollar amount')
    )
 
-Axis labels can also be easily removed:
+Axis labels can be easily removed:
 
 .. altair-plot::
 
@@ -303,6 +303,21 @@ Axis labels can also be easily removed:
        alt.Y('y').axis(labels=False)
    )
 
+Axis title can also be rotated:
+
+.. altair-plot::
+
+    alt.Chart(df).mark_circle().encode(
+        alt.X('x').axis(title="x"),
+        alt.Y('y').axis(
+            title="Y Axis Title",
+            titleAngle=0,
+            titleAlign="left",
+            titleY=-2,
+            titleX=0,
+        )
+    )
+
 Additional formatting codes are available; for a listing of these see the
 `d3 Format Code Documentation <https://github.com/d3/d3-format/blob/master/README.md#format>`_.
 

doc/user_guide/encodings/index.rst

@@ -422,8 +422,7 @@ options available to change the sort order:
   sort. For example ``sort='-x'`` would sort by the x channel in descending order.
 - Passing a list to ``sort`` allows you to explicitly set the order in which
   you would like the encoding to appear
-- Passing a :class:`EncodingSortField` class to ``sort`` allows you to sort
-  an axis by the value of some other field in the dataset.
+- Using the ``field`` and ``op`` parameters to specify a field and aggregation operation to sort by.
 
 Here is an example of applying these five different sort approaches on the
 x-axis, using the barley dataset:
@@ -489,7 +488,9 @@ x-axis, using the barley dataset:
 The last two charts are the same because the default aggregation
 (see :ref:`encoding-aggregates`) is ``mean``. To highlight the
 difference between sorting via channel and sorting via field consider the
-following example where we don't aggregate the data:
+following example where we don't aggregate the data
+and use the `op` parameter to specify a different aggregation than `mean`
+to use when sorting:
 
 .. altair-plot::
 
@@ -512,34 +513,45 @@ following example where we don't aggregate the data:
     sortfield = base.encode(
         alt.X('site:N').sort(field='yield', op='max')
     ).properties(
-        title='By Min Yield'
+        title='By Max Yield'
     )
     sortchannel | sortfield
 
-By passing a :class:`EncodingSortField` class to ``sort`` we have more control over
-the sorting process.
-
 
 Sorting Legends
 ^^^^^^^^^^^^^^^
 
-While the above examples show sorting of axes by specifying ``sort`` in the
+Just as how the above examples show sorting of axes by specifying ``sort`` in the
 :class:`X` and :class:`Y` encodings, legends can be sorted by specifying
-``sort`` in the :class:`Color` encoding:
+``sort`` in the encoding used in the legend (e.g. color, shape, size, etc).
+Below we show an example using the :class:`Color` encoding:
 
 .. altair-plot::
 
-    alt.Chart(barley).mark_rect().encode(
-        alt.X('mean(yield):Q').sort('ascending'),
-        alt.Y('site:N').sort('descending'),
+    alt.Chart(barley).mark_bar().encode(
+        alt.X('mean(yield):Q'),
+        alt.Y('site:N').sort('x'),
         alt.Color('site:N').sort([
             'Morris', 'Duluth', 'Grand Rapids', 'University Farm', 'Waseca', 'Crookston'
         ])
     )
 
-Here the y-axis is sorted reverse-alphabetically, while the color legend is
+Here the y-axis is sorted based on the x-values, while the color legend is
 sorted in the specified order, beginning with ``'Morris'``.
 
+In the next example,
+specifying ``field``, ``op`` and ``order``,
+sorts the legend sorted based on a chosen data field
+and operation.
+
+.. altair-plot::
+
+    alt.Chart(barley).mark_bar().encode(
+        alt.X('mean(yield):Q'),
+        alt.Y('site:N').sort('x'),
+        color=alt.Color('site').sort(field='yield', op='max', order='ascending')
+    )
+
 Datum and Value
 ~~~~~~~~~~~~~~~