Bryanv/sphinxext (bokeh#8665)

* clean up bokeh_enum.py

* add bokeh.sphinxext.bokeh_color to refguide

* clean up bokeh_autodoc.py

* clean up bokeh_color.py

* clean up bokeh_directive.py

* clean up bokeh_github.py

* clean up and add bokeh_jinja.py

* clean up bokeh_model.py

* clean up and add bokeh_options.py

* update outdated intersphinx URLs

* clean up bokeh_palette_group.py

* clean up bokeh_palette.py

* clean up bokeh_prop.py

* clean up bokeh_releases.py

* clean up bokeh_sitemap.py

* clean up collapsible_code_block.py

* clean up example_handler.py

* clean up sample.py

* don't use PackageLoader for templates

* remove cruft from makefile

* update bokeh_gallery to generate .rst detail files at startup

* simplify bokeh-plot and always use relative links to scripts

* migration notes

bokeh/core/has_props.py

@@ -656,12 +656,13 @@ def _clone(self):
 
 '''
 
+# The "../../" is needed for bokeh-plot to construct the correct path to examples
 _EXAMPLE_TEMPLATE = '''
 
     Example
     -------
 
-    .. bokeh-plot:: ../%(path)s
+    .. bokeh-plot:: ../../%(path)s
         :source-position: below
 
 '''

bokeh/sphinxext/_templates/gallery_detail.rst

@@ -0,0 +1,10 @@
+:orphan:
+
+.. index::
+   single: examples; {{ filename }}
+
+{{ filename }}
+{{ '-' * filename|length }}
+
+.. bokeh-plot:: {{ source_path }}
+    :source-position: below

bokeh/sphinxext/_templates/jinja_detail.rst

@@ -1,6 +1,7 @@
 .. data:: {{ name }}
     :module: {{ module }}
     :annotation: = {{ objrepr }}
+    {% if noindex %}:noindex:{% endif %}
 
     {% if doc %}{{ doc|indent(4) }}{% endif %}
 

bokeh/sphinxext/bokeh_autodoc.py

@@ -4,13 +4,18 @@
 #
 # The full license is in the file LICENSE.txt, distributed with this software.
 #-----------------------------------------------------------------------------
-""" Integrate Bokeh extensions into Sphinx autodoc.
+''' Integrate Bokeh extensions into Sphinx autodoc.
 
-Ensures that autodoc directives such as ``autoclass`` automatically
-use Bokeh-specific directives (e.g., ``bokeh-prop`` and ``bokeh-model``)
-when appropriate.
+Ensures that autodoc directives such as ``autoclass`` automatically make use of
+Bokeh-specific directives when appropriate. The following Bokeh extensions are
+configured:
 
-"""
+* :ref:`bokeh.sphinxext.bokeh_color`
+* :ref:`bokeh.sphinxext.bokeh_enum`
+* :ref:`bokeh.sphinxext.bokeh_model`
+* :ref:`bokeh.sphinxext.bokeh_prop`
+
+'''
 
 #-----------------------------------------------------------------------------
 # Boilerplate
@@ -65,6 +70,12 @@ class ColorDocumenter(ModuleLevelDocumenter):
     def can_document_member(cls, member, membername, isattr, parent):
         return isinstance(member, Color)
 
+    # We don't need/want anything from the actual NamedColor class
+    def add_content(self, more_content, no_docstring=False):
+        pass
+    def get_object_members(self, want_all):
+        return False, []
+
 class EnumDocumenter(ModuleLevelDocumenter):
     directivetype = 'bokeh-enum'
     objtype = 'enum'
@@ -94,6 +105,7 @@ def can_document_member(cls, member, membername, isattr, parent):
         return isinstance(member, class_types) and issubclass(member, Model)
 
 def setup(app):
+    ''' Required Sphinx extension setup function. '''
     app.add_autodocumenter(ColorDocumenter)
     app.add_autodocumenter(EnumDocumenter)
     app.add_autodocumenter(PropDocumenter)

bokeh/sphinxext/bokeh_color.py

@@ -4,14 +4,22 @@
 #
 # The full license is in the file LICENSE.txt, distributed with this software.
 #-----------------------------------------------------------------------------
-""" Document Bokeh color objects.
+''' Document Bokeh named colors.
 
-The ``bokeh-color`` directive generates a color swatch for named colors
-in the ``bokeh.colors`` module:
+The ``bokeh-color`` directive accepts a named color as its argument:
+
+.. code-block:: rest
+
+    .. bokeh-color:: aliceblue
+
+and generates a labeled color swatch as output.
 
     .. bokeh-color:: aliceblue
 
-"""
+The ``bokeh-color`` direction may be used explicitly, but it can also be used
+in conjunction with the :ref:`bokeh.sphinxext.bokeh_autodoc` extension.
+
+'''
 
 #-----------------------------------------------------------------------------
 # Boilerplate
@@ -29,6 +37,7 @@
 
 # External imports
 from docutils import nodes
+from docutils.parsers.rst.directives import unchanged
 
 # Bokeh imports
 from bokeh.colors import named
@@ -55,19 +64,21 @@
 
 class BokehColorDirective(BokehDirective):
 
-    has_content = True
+    has_content = False
     required_arguments = 1
-    optional_arguments = 2
+    option_spec = {
+        'module': unchanged,
+    }
 
     def run(self):
-
         color = self.arguments[0]
 
         html = COLOR_DETAIL.render(color=getattr(named, color).to_css(), text=color)
         node = nodes.raw('', html, format="html")
         return [node]
 
 def setup(app):
+    ''' Required Sphinx extension setup function. '''
     app.add_directive_to_domain('py', 'bokeh-color', BokehColorDirective)
 
 #-----------------------------------------------------------------------------

bokeh/sphinxext/bokeh_directive.py

@@ -4,7 +4,7 @@
 #
 # The full license is in the file LICENSE.txt, distributed with this software.
 #-----------------------------------------------------------------------------
-'''
+''' Provide a base class and useful functions for Bokeh Sphinx directives.
 
 '''
 
@@ -41,7 +41,7 @@
     r'''^ ([\w.]*\.)?            # class name(s)
           (\w+)  \s*             # thing name
           (?: \((.*)\)           # optional: arguments
-           (?:\s* -> \s* (.*))?  #           return annotation
+           (?:\s* -> \s* (.*))?  # return annotation
           )? $                   # and nothing more
           ''', re.VERBOSE)
 

bokeh/sphinxext/bokeh_enum.py

@@ -4,32 +4,42 @@
 #
 # The full license is in the file LICENSE.txt, distributed with this software.
 #-----------------------------------------------------------------------------
-""" Thoroughly document Bokeh enumerations
+''' Thoroughly document Bokeh enumerations
 
-The ``bokeh-enum`` directive generates useful type information
-for the enumeration, including all the allowable values. If the
-number of values is large, the full list is put in a collapsible
-code block.
+The ``bokeh-enum`` directive generates useful documentation for enumerations,
+including all the allowable values. If the number of values is large, the full
+list is put in a collapsible code block.
 
-This directive takes the name of a Bokeh enum variable and the
-module to find the value as an argument::
+This directive takes the name of a Bokeh enum variable as the argument and the
+module name as an option. An optional description may be added as content:
+
+.. code-block:: rest
 
     .. bokeh-enum:: baz
         :module: bokeh.sphinxext.sample
 
+        Specify a baz style
+
 Examples
 --------
 
-For the following definition of ``bokeh.sphinxext.sample.Bar``::
-
-    baz = enumeration("a", "b", "c")
-
-the above usage yields the output:
+The directive above will generate the following output:
 
     .. bokeh-enum:: baz
         :module: bokeh.sphinxext.sample
 
-"""
+        Specify a baz style
+
+Although ``bokeh-enum`` may be used explicitly, it is more often convenient in
+conjunction with the :ref:`bokeh.sphinxext.bokeh_autodoc` extension. Together,
+the same output above will be generated directly from the following code:
+
+.. code-block:: python
+
+    #: Specify a baz style
+    baz = enumeration("a", "b", "c")
+
+'''
 
 #-----------------------------------------------------------------------------
 # Boilerplate
@@ -49,7 +59,6 @@
 
 # External imports
 from docutils.parsers.rst.directives import unchanged
-
 from sphinx.errors import SphinxError
 
 # Bokeh imports
@@ -63,7 +72,6 @@
 __all__ = (
     'BokehEnumDirective',
     'setup',
-    'wrapper',
 )
 
 #-----------------------------------------------------------------------------
@@ -74,21 +82,16 @@
 # Dev API
 #-----------------------------------------------------------------------------
 
-wrapper = textwrap.TextWrapper(subsequent_indent='    ')
-
 class BokehEnumDirective(BokehDirective):
 
     has_content = True
     required_arguments = 1
-    optional_arguments = 2
-
     option_spec = {
         'module': unchanged,
         'noindex': lambda x: True, # directives.flag weirdly returns None
     }
 
     def run(self):
-
         name = self.arguments[0]
 
         try:
@@ -101,7 +104,7 @@ def run(self):
         fullrepr = repr(enum)
         if len(fullrepr) > 180:
             shortrepr = fullrepr[:40] + " .... " + fullrepr[-40:]
-            fullrepr = wrapper.wrap(fullrepr)
+            fullrepr = _wrapper.wrap(fullrepr)
         else:
             shortrepr = fullrepr
             fullrepr = None
@@ -118,12 +121,15 @@ def run(self):
         return self._parse(rst_text, "<bokeh-enum>")
 
 def setup(app):
+    ''' Required Sphinx extension setup function. '''
     app.add_directive_to_domain('py', 'bokeh-enum', BokehEnumDirective)
 
 #-----------------------------------------------------------------------------
 # Private API
 #-----------------------------------------------------------------------------
 
+_wrapper = textwrap.TextWrapper(subsequent_indent='    ')
+
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------