Repository: vega/altair

Issue:
Upgrade Altair documentation page
The more I use Altair the more I found myself lost in the documentation [page](https://altair-viz.github.io). Something that I don't feel when I'm on the doc page on the Vega-lite side.

I almost don't dare to say it, but with the continuous growth of possibilities and users, maybe its time to redo the doc page to get it more aligned with the Vega-lite side..



Discussion:
Sure, what suggestions do you have?
Eventually I'm able to find the information I need, but currently its a bit hidden in the closed directory structure on the left. 

I wish to have a vertical bar on the top to go to specific parts in the documentation. Something like the current Vega-Lite or Pandas docs.
<img width="1053" alt="image" src="https://user-images.githubusercontent.com/5186265/75584137-5d375b00-5a6f-11ea-8d2b-c3b2f49002c1.png">

<img width="1053" alt="image" src="https://user-images.githubusercontent.com/5186265/75584089-4264e680-5a6f-11ea-8e7c-b0e566d17125.png">

This will split the amount of information in the current directory structure significantly.

In the Vega-Lite docs I like the clear minimalistic categorisation of options under Transform, Mark, Encoding, View composition and Selections. Especially the inclusion of the various mark types, which is very much the core of any visualisation.
<img width="151" alt="image" src="https://user-images.githubusercontent.com/5186265/75584966-4f82d500-5a71-11ea-96f6-d446bd213a50.png">

By the way, in the docs of Vega-Lite there are no options under Data / Datasets:
<img width="151" alt="image" src="https://user-images.githubusercontent.com/5186265/75585244-e5b6fb00-5a71-11ea-9bcc-199f15df6433.png">
I think there should be some sub-options, especially for Altair.

Furthermore I won't deny that the adopted font size and usage of white gives a pleasant reading experience in the Vega-Lite docs (vs both Pandas and Altair docs). 
Great! The source is in ``docs`` and a lot of the Altair-specific sphinx functionality is in ``altair/sphinxext``. Give it a whirl and see if you can come up with some tweaks that will bring it closer to how you wish it was.

I won't lie though: fine-tuning sphinx themes is not easy or fun.
How fixed are you on sphinx? Will the fun(potential contributors) increase when using Jekyll / markdown?
I chose sphinx because it provides the ability to do auto-documentation based on Python docstrings, and makes it easy to define custom directives (for things like embedding Altair plots and generating the gallery)

I wouldn't be opposed to moving to another system if that would be easier to maintain and update.
Ok, thanks for prompt response. I'm not jumping directly on this issue, but at least some info is documented here.
I adopted the pydata-sphinx-[theme](https://github.com/pydata/pydata-sphinx-theme) and made a few changes in the organisation of files and the result is already very clean.

See following animated gif:
![ezgif com-video-to-gif](https://user-images.githubusercontent.com/5186265/109842117-0815c280-7c4a-11eb-8398-8d7faefa0c4d.gif)

By including [nbsphinx](https://nbsphinx.readthedocs.io/en/0.8.2/) as extension we can organise most of the documentation-pages as notebooks (like Jupyter book).

Progress at least!

Awesome! That would be really great.

Regarding nbsphinx... I recently transitioned another project from nbsphinx to myst-nb, and I'm finding the latter to be a much cleaner way to integrate notebooks into sphinx docs.
@mattijn Is it ok if I look into updating the docs for 5.0 or do you have some specific changes you want to make that are already in progress? I am thinking of doing something very similar as what you suggest here with changing the theme to look more like the Vega docs and I am curious to what reorganization you had in mind. I don't think I will switch the docs over to notebooks for the time being, but I agree that jupyter books with myst is a very nice way to work with documentation in general and what I use for new projects myself. 
Sure, go ahead! I had a try with the suggestions above at that time. At that moment I struggled a bit with 
(1) apply a new theme while maintaining the url-references on the internet still point to the right page, or 
(2) restructure the documentation and accept that references elsewhere on the internet needs to be updated.

I tried 1, but if you improve the structure significantly, just do 2.
You were able to make any progress on this @joelostblom?
Nope, I got caught up in too many things at work. I'm planning to revisit when I have more time, but probably not until late Feb so feel free to work on this if you have time and think 5.0 will be out before I get back on this.
No problem. Lets see, good to know👍 

Resolving patch:
diff --git a/altair/sphinxext/altairgallery.py b/altair/sphinxext/altairgallery.py
--- a/altair/sphinxext/altairgallery.py
+++ b/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,7 +59,7 @@
    <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 %}
@@ -67,13 +67,16 @@
 
    <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:
 """
 )
 
diff --git a/doc/conf.py b/doc/conf.py
--- a/doc/conf.py
+++ b/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,7 +67,7 @@
 
 # General information about the project.
 project = "Altair"
-copyright = "2016-2022, Altair Developers"
+copyright = "2016-{}, Altair Developers".format(datetime.now().year)
 author = "Altair Developers"
 
 # The version info for the project you're documenting, acts as replacement for
@@ -73,7 +75,7 @@
 # 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.


Test patch: