Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reinstate htmlsingle and PDF reference docs #16854

philwebb opened this issue May 14, 2019 · 2 comments


None yet
2 participants
Copy link

commented May 14, 2019

b527d36 has reintroduced the single page documentation but it's not all that discoverable since the multi-page version always shows up at which hides the fact that the file exists.

I think we should try to also restore the previous folder structure.

@philwebb philwebb added this to the 2.2.x milestone May 14, 2019


This comment has been minimized.

Copy link

commented May 15, 2019

I think reinstating the former htmlsingle folder only solves one problem: keeping those URLs alive, like for existing browser bookmarks.

Now the discoverability/docs variants problem is much bigger than that:

  • we're not consistent when pointing to the reference docs on our project page; sometimes pointing the single page, other to the multi-page version
  • browsing the static server index pages IMO does not count as a nice way to discover documentation variants
  • in the 2.1.x line we were generating the docs twice independently and then trying to link one to another (without any guarantee, just relative links)

I think we should solve the problem in two parts:

  1. make sure that those bookmarks are still valid for the well-known aliases like /current and /current-SNAPSHOT. A rewrite rule or an index page that redirects to the new one should work.
  2. find a way to make the single page variant easier to find, but still linking to the multi-page one by default (friendlier for slower Internet connections and devices). Maybe a proper link on the multi-page index as well (and not only the documentation overview section?)

@philwebb philwebb changed the title Reinstate HTML single folder Reinstate htmlsingle and PDF reference docs Jun 18, 2019

@philwebb philwebb modified the milestones: 2.2.x, 2.2.0.M4 Jun 18, 2019

@philwebb philwebb closed this in 1e0cf96 Jun 18, 2019


This comment has been minimized.

Copy link
Member Author

commented Jun 18, 2019

I think I've restored the html, htmlsingle and pdf folders which should get us back to parity with 2.1.x.

@bclozel Do we need to open new issues to cover the additional items from your comment above?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.