Skip to content

Bryanv/11489 example docstrings#11540

Merged
tcmetzger merged 18 commits intobranch-2.4from
bryanv/11489_example_docstrings
Sep 2, 2021
Merged

Bryanv/11489 example docstrings#11540
tcmetzger merged 18 commits intobranch-2.4from
bryanv/11489_example_docstrings

Conversation

@bryevdv
Copy link
Copy Markdown
Member

@bryevdv bryevdv commented Aug 31, 2021 •
edited
Loading

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.

Screen Shot 2021-08-30 at 21 42 11

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.

@bryevdv bryevdv added this to the 2.4 milestone Aug 31, 2021
@tcmetzger
Copy link
Copy Markdown
Member

tcmetzger commented Aug 31, 2021

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

mattpap
mattpap reviewed Sep 1, 2021
View reviewed changes
mattpap
mattpap reviewed Sep 1, 2021
View reviewed changes
mattpap
mattpap reviewed Sep 1, 2021
View reviewed changes
@bryevdv
Copy link
Copy Markdown
Member Author

bryevdv commented Sep 1, 2021

@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

Screen Shot 2021-09-01 at 11 40 41

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 bryevdv requested review from a user, mattpap and tcmetzger September 1, 2021 21:21
@bryevdv
Copy link
Copy Markdown
Member Author

bryevdv commented Sep 1, 2021 •
edited
Loading

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
tcmetzger reviewed Sep 2, 2021
View reviewed changes
Copy link
Copy Markdown
Member

@tcmetzger tcmetzger left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Copy Markdown
Member

tcmetzger commented Sep 2, 2021

@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.

image

@bryevdv
Copy link
Copy Markdown
Member Author

bryevdv commented Sep 2, 2021

@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
Copy link
Copy Markdown
Member Author

bryevdv commented Sep 2, 2021

@tcmetzger I've updated all the docstrings.

@tcmetzger tcmetzger merged commit 8a8875c into branch-2.4 Sep 2, 2021
@mattpap mattpap deleted the bryanv/11489_example_docstrings branch September 2, 2021 21:51
@tcmetzger tcmetzger mentioned this pull request Oct 26, 2021
Closed
This was referenced Dec 6, 2021
Closed
Closed
Merged
bryevdv added a commit that referenced this pull request Dec 13, 2021
@bryevdv
example docstrings (#11540)
88d1e01 
* make options optional / add error checking

* remove ref to old nbviewer site

* first batch

* split categorical.py into heatmap and dotplot

* breadcrumbs for refs

* second batch

* fix badly name annotations references

* third batch

* fourth batch

* remove debugger

* some sampledata page fixes

* another batch

* small fixes

* move some assumtions into the directive

* another batch

* remove streamline/quiver gallery example

* last batch

* update verbiage
@github-actions
Copy link
Copy Markdown

github-actions bot commented Oct 26, 2024

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.

@github-actions github-actions bot locked as resolved and limited conversation to collaborators Oct 26, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

@tcmetzger tcmetzger tcmetzger left review comments

@mattpap mattpap Awaiting requested review from mattpap

Assignees

No one assigned

Labels

status: accepted

Projects

None yet

Milestone

2.4

Development

Successfully merging this pull request may close these issues.

[FEATURE] Enhanced docstrings for gallery entries

3 participants

@bryevdv @tcmetzger @mattpap