Address Sphinx warnings

README.md

@@ -59,7 +59,7 @@ points = alt.Chart(source).mark_point().encode(
     x='Horsepower',
     y='Miles_per_Gallon',
     color=alt.condition(brush, 'Origin', alt.value('lightgray'))
-).add_selection(
+).add_params(
     brush
 )
 
@@ -211,23 +211,8 @@ visualization.
 
 ## Development install
 
-Vega-Altair requires the following dependencies:
-
-* [pandas](https://pandas.pydata.org/)
-* [traitlets](https://github.com/ipython/traitlets)
-* [IPython](https://github.com/ipython/ipython)
-
-If you have cloned the repository, run the following command from the root of the repository:
-
-```
-pip install -e .[dev]
-```
-
-If you do not wish to clone the repository, you can install using:
-
-```
-pip install git+https://github.com/altair-viz/altair
-```
+Instructions on how to install Vega-Altair for development can be found in
+[the documentation](https://altair-viz.github.io/getting_started/installation.html).
 
 ## Testing
 

altair/examples/us_population_over_time.py

@@ -15,7 +15,7 @@
     name="Year",
     fields=["year"],
     bind=alt.binding_range(min=1900, max=2000, step=10, name="Year"),
-    init={"year": 2000},
+    value={"year": 2000},
 )
 
 alt.Chart(source).mark_bar().encode(

altair/sphinxext/altairgallery.py

@@ -97,6 +97,7 @@
 
 EXAMPLE_TEMPLATE = jinja2.Template(
     """
+:orphan:
 :html_theme.sidebar_secondary.remove:
 
 .. This document is auto-generated by the altair-gallery extension. Do not modify directly.

altair/sphinxext/schematable.py

@@ -1,13 +1,18 @@
 import importlib
 import re
+import sys
 import warnings
+from os.path import abspath, dirname
 
-from docutils import nodes, utils
+from docutils import nodes, utils, frontend
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst.directives import flag
-from recommonmark.parser import CommonMarkParser
+from myst_parser.docutils_ import Parser
 from sphinx import addnodes
 
+sys.path.insert(0, abspath(dirname(dirname(dirname(__file__)))))
+from tools.schemapi.utils import fix_docstring_issues  # noqa: E402
+
 
 def type_description(schema):
     """Return a concise type description for the given schema"""
@@ -121,11 +126,14 @@ def build_row(item):
     row += nodes.entry("", par_type, classes=["vl-type-def"])
 
     # Description
-    md_parser = CommonMarkParser()
+    md_parser = Parser()
     # str_descr = "***Required.*** " if required else ""
     str_descr = ""
     str_descr += propschema.get("description", " ")
-    doc_descr = utils.new_document("schema_description")
+    str_descr = fix_docstring_issues(str_descr)
+    document_settings = frontend.get_default_settings()
+    document_settings.setdefault("raw_enabled", True)
+    doc_descr = utils.new_document("schema_description", document_settings)
     md_parser.parse(str_descr, doc_descr)
 
     # row += nodes.entry('', *doc_descr.children, classes="vl-decsr")