DOCS: Revamp docs for the 5.0 release

altair/sphinxext/altairgallery.py

@@ -45,7 +45,7 @@
 
 .. code-block:: none
 
-   $ pip install vega_datasets
+   python -m pip install vega_datasets
 
 {% for grouper, group in examples %}
 
@@ -59,21 +59,24 @@
    <span class="gallery">
    {% for example in group %}
    <a class="imagegroup" href="{{ example.name }}.html">
-     <span class="image" alt="{{ example.title }}" style="background-image: url({{ image_dir }}/{{ example.name }}-thumb.png);"></span>
+     <span class="image" alt="{{ example.title }}" style="background-image: url(..{{ image_dir }}/{{ example.name }}-thumb.png);"></span>
      <span class="image-title">{{ example.title }}</span>
    </a>
    {% endfor %}
    </span>
 
    <div style='clear:both;'></div>
 
+{% endfor %}
+
+
 .. toctree::
-  :hidden:
-{% for example in group %}
-  {{ example.name }}
-{%- endfor %}
+   :maxdepth: 2
+   :caption: Examples
+   :hidden:
 
-{% endfor %}
+   Gallery <self>
+   Tutorials <../case_studies/exploring-weather>
 """
 )
 
@@ -84,7 +87,7 @@
     <div id="showcase">
       <div class="examples">
       {% for example in examples %}
-        <a class="preview" href="{{ gallery_dir }}/{{ example.name }}.html" style="background-image: url({{ image_dir }}/{{ example.name }}-thumb.png)"></a>
+        <a class="preview" href="{{ gallery_dir }}/{{ example.name }}.html" style="background-image: url(.{{ image_dir }}/{{ example.name }}-thumb.png)"></a>
       {% endfor %}
       </div>
     </div>
@@ -105,9 +108,6 @@
     {% if strict %}:strict:{% endif %}
 
     {{ code | indent(4) }}
-
-.. toctree::
-   :hidden:
 """
 )
 

doc/_static/altair-plot.css

@@ -8,6 +8,5 @@
 .vega-embed {
     margin-bottom: 20px;
     margin-top: 20px;
-    width: 100%;
 }
 

doc/_static/custom.css

@@ -23,4 +23,63 @@ table.docutils td p {
 table.docutils td li {
   line-height: 18px;
 
-}
+}
+
+/* Everything below this comment is for the pydata sphinx theme*/
+
+/* Blue topbar */
+.navbar-light {
+    background-color: #16A7F0 !important;
+}
+/* White text in topbar */
+.navbar-light a {
+    color: #fff !important;
+}
+/* White bold project title in topbar */
+.navbar-light p.title {
+    font-size: 26px !important;
+    font-weight: 800 !important;
+    color: #fff !important;
+    text-align: center;
+    width: 100%;
+}
+/* There is a small jump in the title positionin when the navbar transitions full */
+/* title to the collapse button. 27% width here makes that jump as discrete as possible */
+div#navbar-start {
+    width: 27%;
+    margin-left: 0px !important;
+}
+/* Adjust the title position for narrow screens, such as mobile phones. */
+/* This also prevents that the collapse button stacks under the title, */
+/* which would cover a bit of the logo. 719px makes the title */
+/* switch to narrow screen layout at the same time as the rest of the page. */
+@media only screen and (max-width: 719px) {
+    div#navbar-start {
+        width: 60%;
+        margin-left: 0px !important;
+    }
+    .navbar-light p.title {
+        text-align: right;
+    }
+}
+
+/* Version number in the same darkblue color as other text */
+div.navbar-brand-box p#site-version.site-version {
+    color: #130654 !important;
+}
+/* The box that contains the logo and the version number */
+div.navbar-brand-box a {
+    width: 100% !important;
+    height: auto !important;
+    flex-direction: column !important;
+}
+/* The logo */
+div.navbar-brand-box img {
+    display: block !important;
+    height: auto !important;
+    width: auto !important;
+    max-height: 18vh !important;
+    max-width: 100% !important;
+    margin: 0 auto !important;
+    margin-top: -40px !important;
+}

doc/_templates/navbar-project.html

@@ -0,0 +1,4 @@
+<a class="navbar-brand" href="{{ pathto(master_doc) }}">
+<p class="title">{{ project }}</p>
+</a>
+

doc/_templates/sidebar-logo.html

@@ -0,0 +1,13 @@
+<div class="navbar-brand-box">
+    <a class="navbar-brand text-wrap" href="{{ pathto('index') }}">
+      {% if logo %}
+        <!-- `logo` is deprecated in Sphinx 4.0, so remove this when we stop supporting 3 -->
+        {% set logo_url=logo %}
+      {% endif %}
+      {% if logo_url %}
+      <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo">
+      <br>
+      <p class="site-version" id="site-version">{{ version }}</p>
+      {% endif %}
+    </a>
+</div>

doc/case_studies/exploring-weather.rst

@@ -1,7 +1,7 @@
 .. _exploring-weather:
 
 Exploring Seattle Weather
-=========================
+-------------------------
 
 (This tutorial is adapted from `Vega-Lite's documentation
 <http://vega.github.io/vega-lite/tutorials/explore.html>`_)
@@ -237,7 +237,7 @@ of the selection (for more information on selections, see
     ).properties(
         width=600,
         height=400
-    ).add_selection(
+    ).add_parameter(
         brush
     )
 
@@ -266,3 +266,10 @@ If you want to further customize your charts, you can refer to Altair's
 :ref:`API`.
 
 .. _Pandas: http://pandas.pydata.org/
+
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   self

doc/conf.py

@@ -14,6 +14,7 @@
 
 import sys
 import os
+from datetime import datetime
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -38,6 +39,7 @@
     "altair.sphinxext.altairplot",
     "altair.sphinxext.altairgallery",
     "altair.sphinxext.schematable",
+    # "sphinxext.rediraffe",
 ]
 
 altair_plot_links = {"editor": True, "source": False, "export": False}
@@ -65,15 +67,15 @@
 
 # General information about the project.
 project = "Altair"
-copyright = "2016-2020, Altair Developers"
+copyright = "2016-{}, Altair Developers".format(datetime.now().year)
 author = "Brian Granger and Jake VanderPlas"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = "4.3.0.dev0"
+version = "5.0.0"
 # The full version, including alpha/beta/rc tags.
 release = version
 
@@ -127,12 +129,16 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {
+    "navbar_start": ["navbar-project"],
+    "navbar_center": ["navbar-nav"],
+    "navbar_end": ["navbar-icon-links"],
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -166,6 +172,7 @@ def setup(app):
     app.add_css_file("theme_overrides.css")
     app.add_css_file("custom.css")
 
+
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
@@ -181,7 +188,15 @@ def setup(app):
 # html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+html_sidebars = {
+    "**": ["sidebar-logo", "search-field", "sidebar-nav-bs", "sidebar-ethical-ads"],
+}
+
+# Redirection of old page locations via the rediraffe sphinx-extension
+# It seems like only pages can be redirected, not headings within pages
+# rediraffe_redirects = {
+#     'case_studies/exploring-weather.rst': 'user_guide/case_studies/exploring-weather.rst'
+# }
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

doc/getting_started/overview.rst

@@ -33,3 +33,13 @@ concise grammar.
 
 .. _Vega: http://vega.github.io/vega
 .. _Vega-Lite: http://vega.github.io/vega-lite
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Getting Started
+   :hidden:
+
+   self
+   installation
+   starting

doc/index.rst

@@ -9,88 +9,39 @@ Altair: Declarative Visualization in Python
    :size: 15
 
 Altair is a declarative statistical visualization library for Python, based on
-Vega_ and Vega-Lite_, and the source is available on
-`GitHub <http://github.com/altair-viz/altair>`_.
+Vega_ and Vega-Lite_.
 
 With Altair, you can spend more time understanding your data and its meaning.
 Altair's API is simple, friendly and consistent and built on top of the
 powerful Vega-Lite_ visualization grammar. This elegant simplicity produces
 beautiful and effective visualizations with a minimal amount of code.
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Getting Started
-
-   getting_started/overview
-   getting_started/installation
-   getting_started/starting
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Gallery
+Altair is BSD-licensed and the source is available on `GitHub`_,
+where you can also report `bugs and feature requests`_.
+For general questions, please ask on `StackOverflow`_
+using the `altair` tag.
 
-   gallery/index
+You can browse this documentation
+via the links in the top navigation panel
+or by viewing the full site :ref:`genindex`.
+In addition to reading this documentation page,
+it can be helpful to also browse the `Vega-Lite documentation <https://vega.github.io/vega-lite/docs/>`_.
 
 .. toctree::
    :maxdepth: 1
-   :caption: User Guide
+   :hidden:
 
-   user_guide/data
-   user_guide/encoding
-   user_guide/marks
-   user_guide/transform/index
-   user_guide/interactions
-   user_guide/interactions2
-   user_guide/configuration
-   user_guide/compound_charts
-   user_guide/scale_resolve
-   user_guide/saving_charts
-   user_guide/customization
-   user_guide/times_and_dates
-   user_guide/faq
-   user_guide/troubleshooting
-   user_guide/internals
-   user_guide/API
+   Getting Started <getting_started/overview>
+   User Guide <user_guide/data>
+   Examples <gallery/index>
+   Reference <user_guide/API>
    user_guide/ecosystem
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Case Studies
-
-   case_studies/exploring-weather
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Advanced Usage
-
-   user_guide/importing
-   user_guide/display_frontends
-   user_guide/custom_renderers
-   user_guide/data_transformers
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Release Notes
-
    releases/changes
-
-Bug Reports & Questions
------------------------
-
-Altair is BSD-licensed and the source is available on `GitHub`_. If any
-questions or issues come up as you use Altair, please get in touch via
-`Git Issues`_ or our `Google Group`_.
-
-
-Indices and tables
-------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-
+   Help <user_guide/getting_help>
 
 .. _GitHub: http://github.com/altair-viz/altair
 .. _Git Issues: http://github.com/altair-viz/altair/issues
 .. _Vega: http://vega.github.io/vega
 .. _Vega-Lite: http://vega.github.io/vega-lite
-.. _Google Group: https://groups.google.com/forum/#!forum/altair-viz
+.. _bugs and feature requests: https://github.com/altair-viz/altair/issues/new/choose
+.. _StackOverflow: https://stackoverflow.com/tags/altair

doc/releases/changes.rst

@@ -1,7 +1,7 @@
 .. _changes:
 
-Altair Change Log
-=================
+Release Notes
+=============
 
 Version 4.3.0 (unreleased)
 --------------------------

doc/requirements.txt

@@ -2,5 +2,5 @@ sphinx
 jinja2
 numpydoc
 pillow
-sphinx_rtd_theme
 mistune<=0.8.4
+pydata-sphinx-theme