Address Sphinx warnings (#2758)

* Switch from using recommonmark to myst-parser as the former is deprecated

* Tag gallery examples as sphinx orphan pages to disable warning about them not appearing in any toctree

* Fix reference to image mark page

* Use 'value' instead of deprecated 'init'

* Fix 'The value of 'empty' should be True or False.'

* Replace usage of add_selection with add_params

* Switch from deprecated 'single' selection type to 'point'

* Fix underline length

* Fix wrong indent

* Enable parsing of raw content

* Move myst-parser into doc requirements

* Restrict setuptools to version < 64. See added comment for reasoning

* No longer wrap docstring lines where an attribute is introduced with its types

* Mention myst-parser

* Handle list entires that start with '-' or miss a whitespace after the list sign

* Fix relative link to datetime type

* Fix 'Anonymous hyperlink mismatch'

* Resolve duplicate definitions of Color and Text which appear in channels as well as core (low-level)

* Format code

* Update documentation on dependencies. Remove section in readme and refer to documentation as that section was not maintained

* Move myst-parser requirement into requirements_dev.txt so that it's available for the build workflow

* suppress warning usage geographic CRS for centroid

This PR suppress the following warning to use a projected CRS for geometric computations.
```
<string>:3: UserWarning: Geometry is in a geographic CRS. Results from 'centroid' are likely incorrect. Use 'GeoSeries.to_crs()' to re-project geometries to a projected CRS before this operation.
```
For the given example we only need a _visual_ centroid and not an _exact_ centroid so this merely promotes good practice than being a necessity.

* Update geoshape.rst :: typo

Co-authored-by: Mattijn van Hoek <mattijn@gmail.com>

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")