Improvements to docs (bokeh#4825)

* docs: make clean clears auto-generated gallery rst files

* docs: fix link

* docs: fix ref replacements

* docs: fix indent warning

* docs; clear gallery before generating the new one

* docs: fix role warnings

* docs: fix unexpected indentation error in docstring

* docs: drop the inheritance diagram (and graphviz dependency)

* docs: fix gallery builder

* style

* flake

bokeh/models/annotations.py

@@ -565,6 +565,7 @@ class Title(TextAnnotation):
     offset = Float(default=0, help="""
     Offset the text by a number of pixels (can be positive or negative). Shifts the text in
     different directions based on the location of the title:
+
         * above: shifts title right
         * right: shifts title down
         * below: shifts title right

bokeh/sphinxext/bokeh_gallery.py

@@ -4,7 +4,7 @@
 from __future__ import absolute_import
 
 import json
-from os import makedirs
+from os import makedirs, listdir, remove
 from os.path import abspath, dirname, exists, join
 
 from docutils import nodes
@@ -65,7 +65,6 @@ def run(self):
         env.note_reread()
 
         dest_dir = join(dirname(self.state_machine.node.source), "gallery")
-        if not exists (dest_dir): makedirs(dest_dir)
 
         target_id = "bokeh-plot-%d" % env.new_serialno('bokeh-plot')
         target_node = nodes.target('', '', ids=[target_id])
@@ -117,5 +116,13 @@ def env_updated_handler(app, env):
     return getattr(env, 'gallery_names', [])
 
 def setup(app):
+
+    # Clear gallery before generating a new one
+    dirname = 'source/docs/gallery'
+    if not exists(dirname):
+        makedirs(dirname)
+    for fname in listdir(dirname):
+        remove(join(dirname, fname))
+
     app.connect('env-updated', env_updated_handler)
     app.add_directive('bokeh-gallery', BokehGalleryDirective)

bokeh/sphinxext/bokeh_github.py

@@ -165,15 +165,16 @@ def make_gh_link_node(app, rawtext, role, kind, api_type, id, options=None):
 
 
 def _try_url(app, url, role):
+    url = url[:8] + urllib.parse.quote(url[8:])  # spaced to %20 etc.
     try:
         request = urllib.request.Request(url)
         request.get_method = lambda : 'HEAD'
         response = urllib.request.urlopen(request, timeout=5)
     except (urllib.error.HTTPError, urllib.error.URLError):
-        app.warn("URL '%s' for :bokeh-%s: role could not be loaded" % (url, role))
+        app.warn("URL '%s' for :bokeh-%s: role is not available on GitHub" % (url, role))
     else:
         if response.getcode() >= 400:
-            app.warn("URL '%s' for :bokeh-%s: role could not be loaded" % (url, role))
+            app.warn("URL '%s' for :bokeh-%s: role is not available on GitHub" % (url, role))
 
 def setup(app):
     app.add_role('bokeh-commit', bokeh_commit)

bokeh/sphinxext/bokeh_prop.py

@@ -30,6 +30,7 @@ class Bar(Model):
 
 from docutils import nodes
 from docutils.statemachine import ViewList
+from docutils.core import publish_parts
 
 import textwrap
 
@@ -93,6 +94,14 @@ def run(self):
             doc="" if prop.__doc__ is None else textwrap.dedent(prop.__doc__),
         )
 
+        # Set this to True to hunt for Sphynx warning (e.g. unexpected indentation)
+        if False and prop.__doc__:
+            print('--', prop_name)
+            try:
+                publish_parts(prop.__doc__)
+            except Exception as err:
+                print('Error in docstring: ' + str(err))
+
         result = ViewList()
         for line in rst_text.split("\n"):
             result.append(line, "<bokeh-prop>")

bokeh/tile_providers.py

@@ -1,7 +1,9 @@
-''' Pre-configured tile sources with urls and attribution for common 3rd-party tile services.
-    Additional information available at:
-        Stamen tile service - http://maps.stamen.com/
-        CartoDB tile service - https://carto.com/location-data-services/basemaps/
+'''
+Pre-configured tile sources with urls and attribution for common 3rd-party tile services.
+Additional information available at:
+
+* Stamen tile service - http://maps.stamen.com/
+* CartoDB tile service - https://carto.com/location-data-services/basemaps/
 '''
 from .models.tiles import WMTSTileSource
 

conda.recipe/meta.yaml

@@ -45,7 +45,6 @@ requirements:
 test:
   requires:
     # docs
-    - graphviz
     - pygments
     - sphinx >=1.3.1
 

scripts/devdeps.py

@@ -72,7 +72,6 @@ def depend_check(deps_name, *args):
     depend_check('Dev', *dev_deps)
 
     docs_deps = [
-        'graphviz',
         'sphinx',
         'pygments',
     ]

sphinx/Makefile

@@ -26,6 +26,7 @@ all: html
 
 clean:
 	-rm -rf $(BUILDDIR)/*
+	-rm -rf source/docs/gallery/*
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

sphinx/make.bat

@@ -29,6 +29,7 @@ if "%1" == "help" (
 if "%1" == "clean" (
 	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
 	del /q /s %BUILDDIR%\*
+	del /q /s source\docs\gallery\*
 	goto end
 )
 

sphinx/source/conf.py

@@ -29,9 +29,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
-    'sphinx.ext.graphviz',
     'sphinx.ext.ifconfig',
-    'sphinx.ext.inheritance_diagram',
     'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx',
     'bokeh.sphinxext.bokeh_autodoc',

sphinx/source/docs/dev_guide/testing.rst

@@ -193,6 +193,6 @@ The examples.log link does not get reported in the POOR MAN LOGGER. To find it,
 either search for ``EXAMPLES LOG SUCCESSFULLY UPLOADED`` in the test log, or
 just click on the html report and then change html for log.
 
-.. _custom_markers: http://pytest.org/latest/example/markers.html#working-with-custom-markers
+.. _custom markers: http://pytest.org/latest/example/markers.html#working-with-custom-markers
 .. _SauceLabs: http://saucelabs.com/
 .. _selenium webdriver: http://docs.seleniumhq.org/docs/03_webdriver.jsp

sphinx/source/docs/reference/core.rst

@@ -45,12 +45,6 @@ and property mixins. Property classes provide automatic validation and
 serialization for a large collection of useful types. Mixin and container
 classes provide for easy bulk addition of properties to model classes.
 
-Below is the full class inheritance diagram for all standard Bokeh property
-types. Click on any node to be taken to the corresponding documentation.
-
-.. inheritance-diagram:: bokeh.core.properties
-  :parts: 1
-
 .. automodule:: bokeh.core.properties
     :members:
 

sphinx/source/docs/user_guide/bokehjs.rst

@@ -145,7 +145,7 @@ The JavaScript ``Bokeh.Plotting`` API is a port of the Python
 reference in addition to the material here.
 
 Here is an example that is very similar the Python example
-:bokeh-tree:`examples/plotting/file/color_scatterplot.py`:
+:bokeh-tree:`examples/plotting/file/color_scatter.py`:
 
 .. code-block:: javascript
 

sphinx/source/docs/user_guide/plotting.rst

@@ -372,6 +372,11 @@ Adding Annotations
 The section on adding annotations to plots has moved.  Please see
 :ref:`userguide_annotations`
 
+.. |bokeh.plotting| replace:: :ref:`bokeh.plotting <bokeh.plotting>`
+.. |Figure| replace:: :class:`~bokeh.plotting.figure.Figure`
+.. |figure| replace:: :func:`~bokeh.plotting.figure`
+.. |Plot| replace:: :class:`~bokeh.models.plots.Plot`
+
 .. |annular_wedge|     replace:: :func:`~bokeh.plotting.figure.Figure.annular_wedge`
 .. |annulus|           replace:: :func:`~bokeh.plotting.figure.Figure.annulus`
 .. |arc|               replace:: :func:`~bokeh.plotting.figure.Figure.arc`