Cross-referencing the documentation, user guide, and examples

Community Support
1

From a reply from @Bryan:

We have example scripts in the examples directory that demonstrate [accepting HTTP request arguments] and may other things. I’ve thought for a long time that it would be good to find a way to automate cross-referencing these examples to the narrative and reference docs. Just getting to a place that let’s you know what the right term or concept is at all is an important step, but then seeing an immediate example of the concept in practice would be even more valuable.

I thought it’d be a good idea to get a topic going about improving the documentation/reference/examples.

2

In getting to know Bokeh over the last month, here are some things I feel like the website/documentation does well:

  • The attributes of every Bokeh object are explicitly listed, along with possible values they can take.
  • The tutorial is shiny and inviting, and made implementing many common use cases easy. I think the accessibility of the tutorial kept me interested through any rough edges the first week or so.
  • The gallery effectively demonstrates why Bokeh is not just CSSed matplotlib.

Here are some points where I struggled:

  • The User Guide is for explaining implementation patterns, I think. With the way it’s set up now, reading through from beginning to end is not very appealing. I think it’s too disconnected from the examples and tutorials.
  • The reference was useful once I understood what it was. Navigating through the class hierarchies was sometimes a pain. There was no single location listing all the attributes of a single class.

Anyway, I’m all for figuring out how to automate the cross-referencing of the user guide, reference, examples, and tutorials. On each doc page, matplotlib.org has a nice (automated?) list of links to examples using the function discussed. (Here’s the colorbar page as an example.) Luckily, Bokeh’s examples are a lot prettier, and I think something like that would be a much more attractive feature on Bokeh’s documentation.

3

@kylrth Thank you for starting this topic! I want to dive a little deeper into your comments if I can.

The User Guide is for explaining implementation patterns, I think. With the way it’s set up now, reading through from beginning to end is not very appealing. I think it’s too disconnected from the examples and tutorials.

In my mind, the major failing of the User Guide currently is that it is lacking cross references to complete examples, and to the ref guide. I think many/all of the narrative sections with snippets should cross reference to relevant complete examples, and/or reference docs sections.

I don’t necessarily see the Users’ Guide as something that anyone would read through start to finish. Rather I see it as organized by topic, so that it can be useful for users working in a given topic area.

Roughly speaking, in my mind:

  • Tutorials These are intended to be start-to-finish, in order to bootstrap getting users both the big, high level picture, as well as the most important conceptual context

  • User Guide Topic-based. You go here when you want to find out about Handling Categorical Data but it’s not necessarily something everyone would read start-to-finish, because many users won’t care at all about some of the topics.

  • Reference Guide For experienced users to look up specific information they already know something about (but just need some detail or other)

Does this seem reasonable? Are there other points of view on this breakdown?

The reference was useful once I understood what it was. Navigating through the class hierarchies was sometimes a pain. There was no single location listing all the attributes of a single class.

This is not the first time this has been raised, and I am not at all unsympathetic to the view that the Reference Guide needs:

  • more information per entry, as a rule
  • more entries repeated (so users don’t have to follow inheritance hierarchies)

There is a Sphinx option to turn on showing all attributes on all classes (i.e even all inherited ones) The only reasons I have resisted this are:

  • The ref guide has often has lots of classes per page. Turning this option on trades one problem for another in my mind: now you have a “needle in a haystack” situation because individual ref guide pages become enormous.

  • There are a lot of somewhat internal attributes that are really just noise for regular users.

To address this I would propose:

  • Splitting up the ref guide more discretely, maybe a page per class even
  • Creating a way to mark “advanced” or “developer” options so those can be hidden, or at least hidden by default.

I should add, the Bokeh docs should be migrating to ReadTheDocs soon, which should also restore the site search. I think my first objection above is ameliorated quite a bit when that becomes true.

Some things I might propose:

  • Make is so that examples can contain a narrative doc string that gets displayed on the example page
  • Make is so that examples can state cross-reference terms that get added to the index, and make it easy to reference examples from user guide sections.
  • Implement the two reference guide ideas above, and turn on the option to show all properties for all classes
  • Add more cross referencing to reference guide from user guide, maybe even automatically (there was a PR for something like that sadly fell out of date before it could be merged)

Thoughts on this? Thoughts on other ideas?

1 Like
4

Responses to your proposed ideas:

  • This one confused me. A narrative doc string at the top of the code example? And by “example page” do you mean the gallery?
  • What is the index? Otherwise, yes to this idea. I am the type of person that would enjoy updating the user guide.
  • Is it pretty obvious what attributes are “developer” and which are user-facing? I would still like the reference guide to be able to display the developer attributes, because this guide is useful for development.
  • I would enjoy working on automating these cross-references.

Here’s an attempt at a task list:

  • Add docstrings to examples and display them on the gallery page.
  • Add an option to show/hide developer attributes in the reference guide. If moving to ReadTheDocs makes this easier, sounds good.
  • Cross-reference examples with the reference docs. Automating that would require a tool that finds the Bokeh objects used in an example, and adds links between the example and those objects in the reference guide.
  • Cross-reference the user guide with the examples and reference docs. I’m thinking the reference docs could be referenced (ha) automatically, and then examples could be pulled for objects discussed in the user guide. Any examples demonstrating larger concepts (not relating to specific objects) would have to be referenced by hand.
5
  • This one confused me. A narrative doc string at the top of the code example? And by “example page” do you mean the gallery?

Yes exactly, sorry I could have been clearer. In the past I favored having the examples be as short as possible so they generally don’t have docstrings. But I think each each example should get a docstring, which is good for people reading the source directly, but we can also use the sphinx extensions to render the docstrings nicely in the gallery, and we could also embed keywords for cross-referencing in the docstrings as well.

  • What is the index? Otherwise, yes to this idea. I am the type of person that would enjoy updating the user guide.

Well right now there isn’t really a user-accessibly index, but there could be one. But mostly I meant leveraging the Sphinx indexing capabilities (or writing our own extensions to help) to make it easy to automatically link relevant examples in lots of places.

  • Is it pretty obvious what attributes are “developer” and which are user-facing? I would still like the reference guide to be able to display the developer attributes, because this guide is useful for development.

I’m not sure. :slight_smile: I am way too close to things to say at this point, so it might be a good exercise to have a call/screenshare to do some API review.

  • I would enjoy working on automating these cross-references.

:confetti_ball: awesome!

All of your work plan sounds great. I would say starting with docstrings in the examples is straightforward task. A thing to think about ahead of time is: how do we want to specify important keywords for the example? I.e., we could be explicit in the docstring with a sphinx directive:

''' foo_example.py

This example shows off stuff.

Probably OK to have Markdown here that gets rendered in the docs gallery

:bokeh-keywords: Legend, LinearColorMapper

'''

Something like that? With the idea that we could use the keywords to automatically add links in the rendered gallery page to the docs, and possibly back-links in the docs to the gallery page.