Our document structure can and has changed over the years, so it’s not always the case that a corresponding link exists in newer versions. Here I think we have a difference in value judgment: I would deem it better to omit links entirely, if there is the possibility that they can be wrong, rather than always auto-generate a link to “latest” that may or may not work (even if it usually works).
But that’s why discussion is good. Although it’s not my preference, if someone feels strongly and wants to implement some simple regex to substitute “latest” in the current page URL, the code to update is here:
Regarding searching again, this is another good reason to go to https://docs.bokeh.org as the first step and then utilize the site search from the front page. The site search results are locked to the version you are viewing, so you will never get mis-directed to different versions.
I don’t mean to harp on the site search, but there are so many different ways that different people approach documentation [1] that there will never be a single information architecture that “works” for everyone simultaneously. But I think site search a shortcut around the site organization that can work for everyone, which is why I keep bringing it up as something to promote more or better.
Thanks for the kind words and continued discussion (and for reaching out to Numpy!)
As a specific example: we had complaints both that the reference docs were not complete enough because they did not include base class members in subclasses, and then once we started doing that, complaints that the reference docs are now too bloated and hard to find a needle in a haystack. There is truly never going to be a site organization that will satisfy everyone. ↩︎
The Numpy devs responded rather quickly. Per Remove numpy documentation from google searches · Issue #39 · scipy/docs.scipy.org · GitHub, the issue was fixed by modifying their robots.txt file. Another person mentioned adding a “canonical” link to the pages with <link rel="canonical" href="https://docs.bokeh.org/en/latest/{MODULE}/{SUBMODULE}/{FUNCTION}.html" />. Not sure if that’s helpful…
in the document <head> We don’t have a robots.txt (or rather, it is empty) so we are not putting up any barriers to any crawlers. I have even on occasion kicked off new crawls explicitly from the search console tool for the property. So I am not really sure what else we can/should do.
I guess we could consider engaging project funds to pay someone to sort it out, but I am not sure how to find such a person, or whether this kind of work would fit in our meager budget (our entire account balance is a few thousand USD)
Edit: and looking that the search console tool, Google shows that there were crawls in the last week, and also shows that 11k user-specified canonical pages were understood. We publish an updated sitemap with every docs push too. AFAIK we are doing everything we are supposed to do
For NumPy, the robots.txt file is only for the old dcumentation site under scipy.org. The new site https://numpy.org/doc/1.17/user/c-info.html does not have a robots.txt. It does have a snippet of javascript that provides the red text at the top of older versions, which searches the “stable” docs for the matching doc there. If it finds it, the link is shown. If not the javscript links to the search page, and pre-seeds it with the page title.
It also adds the canonical link to all pages. It was added in this PR.
I’m late to the party here, but I’d like to make some points and make some requests.
First off, a big thank you to Bryan and the team for building Bokeh. Yes it has bugs, yes it has shortcomings, but it’s a huge help to me in my work and I’m very glad the project exists. My life would be much harder without it.
I’d like to contribute in two ways, but I don’t know how. Perhaps you could give me some guidance on the way forward?
I’m a regular user, so I know where the weaknesses are in the documentation. I know where examples are needed. What I don’t know is how to raise what I’ve found as an issue. When I find shortcomings, should I raise them as an issue in Github?
I occasionally build Bokeh-based apps for side-projects (meaning, I ‘own’ the IP and I can do what I like with it). I would be happy to submit projects for the gallery, but I don’t know what criteria you use for selection. I don’t know what kind of apps would be helpful either. If I had a list of what you’re looking for, I could build my next project using your guidelines and submit it to you. As a note, all of my side-projects are more detailed than anything currently in the gallery.
I would love to help you guys build Bokeh better, but I can’t commit time to code. I can commit time for demos and documentation (tutorials?), but I need clear guidance on what you want.
(sorry if I sound frustrated—I am frustrated, though not with anyone here)