Bryanv/11489 example docstrings

[bryevdv]

• issues: fixes [FEATURE] Enhanced docstrings for gallery entries #11489
• release document entry (if new feature or API change)

Updating gallery example to use the new example metadata directive. As a convention, I am making the "refs" links form a series of breadcrumbs which provides more context and affords a better UX. I'm also removing all the output_file calls in the gallery examples, as long as I am touching these files anyway.

cc @tcmetzger @hyles-lineata I will be working on this in batches all week to get it done for 2.4 but any early feedback would be helpful in case there are course corrections to make.

Note that I only plan to update the examples that are part of the gallery in this PR. I would love to see this extended to all examples, so that perhaps one day every example can automatically render it's own individual page that can also be automatically cross-referenced and linked. Maybe we could push hard on a "Bokeh users! Can you contribute just one docstring?" crowdsourcing for the larger project.

[tcmetzger]

@bryevdv Thank you, this looks amazing! I also like the idea of the breadcrumbs!

[bryevdv]

@mattpap @hyles-lineata please c.f. 0ac5f9a which makes writing this possible:

.. bokeh-example-metadata::
    :sampledata: unemployment, us_counties
    :apis: bokeh.plotting.Figure.patches, bokeh.models.mappers.LogColorMapper
    :refs: :ref:`userguide_tools` > :ref:`userguide_tools_hover_tool`
    :keywords: colormap, map, patches

resulting in

I think we may want to eventually tweak the template, lists of things are not quite as distinct as I might like, in which case maybe field lists are not the best choice. But this should do for now.

[bryevdv]

cc @mattpap @hyles-lineata @tcmetzger ready for review. A few comments:

• vector.py example as deleted. It was cool, but not good as an example (only example with hundreds of lines of auxiliary code)
• categorical.py was split into categorical_heatmap.py and dotplot.py
• After those changes, there are no more files that show up in multiple places in gallery under different thumbnails
• Added eclipse.py to gallery
• visible model links all say only bokeh.models.Foo . A step towards my goal for 3.0 to remove all visibility of bokeh.models submodules from users

I might possibly look at implementation improvements if I have time, but I don't plan any content changes except as requested (or please feel free t push edits directly to save time):

• automatic "breadcrumbs"
• arrange APIs in a vertical list for easier reading
• might add more new examples to gallery (feel free to suggest)

[tcmetzger]

Thanks, this PR contains some great improvements, including the added background to the iris dataset and fixing the anchors for annotations!

I left some minor comments/suggestions. One more thought: Most of the texts follow the pattern [A foo plot][demonstrating bar]. I would at least put a comma before "demonstrating", maybe even a period to make things easier to read. For example:

A timeseries plot using stock price data. Demonstrates adding multiple plots to a gridplot.

[tcmetzger]

@bryevdv One more thing: I built the docs from this branch locally and randomly clicked on some of the examples' thumbnails in the gallery page. Most of the linked pages did display the docstrings, but for some, the docstrings didn't show up at all (even though they were present in the code). This happens for example with anscombe, hex_tile, and bar_intervals. This might well be a local issue on my machine, but might be worth looking into to be sure.

[bryevdv]

@tcmetzger might be caching, can you try a force-reload?

A timeseries plot using stock price data. Demonstrates adding multiple plots to a gridplot.

I guess I didn't do this because it seems pretty awkward w/o

A timeseries plot using stock price data. This example demonstrates adding multiple plots to a gridplot.

which seemed repetitive across all the examples. But it's probably the best choice.

[bryevdv]

@tcmetzger I've updated all the docstrings.