Switch to PyData theme

[jpmckinney]

• https://sphinx-book-theme.readthedocs.io/en/latest/ (via https://executablebooks.org/en/latest/tools.html)
  • https://sphinx-book-theme.readthedocs.io/en/latest/layout.html#margins (Extract margin directive to separate repository executablebooks/sphinx-book-theme#327)
  • https://jupyterbook.org/content/layout.html#sidebars-within-content ✅
  • https://jupyterbook.org/content/content-blocks.html#glossaries ✅
  • https://jupyterbook.org/content/content-blocks.html#footnotes ✅
  • Note the GitHub and Download buttons at the top of https://jupyterbook.org/ (https://sphinx-book-theme.readthedocs.io/en/latest/configure.html) 🚫
• https://pydata-sphinx-theme.readthedocs.io/en/latest/ (via https://jupyterbook.org/) ✅
  • sphinx-book-theme is built on top of pydata-sphinx-theme.
  • Pandas uses this theme, and has main sections across the top, pages within the section on the left, and within-page headings on the right. It has panels on the home page for each section.

standard_theme has not been kept up-to-date with its upstream (open-contracting/standard_theme#8). standard_theme also has a variety of issues like the single sidebar mixing in-page and between-page navigation.

We can see what we added in our open_contracting branch, to check if there is anything to carry over to sphinx-book-theme (which we should try to carry-over in a way that makes it easy to track upstream). ✅

Helpful docs, to which we can add a link from standard-development-handbook: ✅

• https://jupyterbook.org/reference/cheatsheet.html
• https://sphinx-book-theme.readthedocs.io/en/latest/reference/demo.html
• https://pydata-sphinx-theme.readthedocs.io/en/latest/demo/ ✅

Inspiration

• https://developers.google.com/drive/api/v3/about-sdk ✅
• https://framework.frictionlessdata.io ✅

[jpmckinney]

As of quite recently, JupyterBook and dependencies have been refreshed: https://jupyterbook.org/reference/_changelog.html#v0-8-0-2020-09-01

[jpmckinney]

• We should use color and shadow to create "layers" like in Google's API docs. Otherwise, it's easy to not notice the right-hand menu.
• We should think through how to interlink the different documentation websites via the top navigation, e.g. Profiles (and OC4IDS), Tools (data service, flattening tool)

Added to checklist at open-contracting/standard#1254 (comment)

[jpmckinney]

A reminder that I'll need to update the crawler for the new theme: open-contracting/ocds-index#6
Done

[jpmckinney]

Comment moved to #36 (comment)

[jpmckinney]

A follow-up issue will be to restore a good print stylesheet, and test its output with make pdf.
Created #44

[jpmckinney]

The relevant features have been documented at https://ocds-standard-development-handbook.readthedocs.io/meta/markdown_style_guide.html

Work continues in open-contracting/standard#1254 (comment)

To close this issue, the theme will need to be implemented in this template and in the other documentation repositories.

[jpmckinney]

See also this heuristic evaluation of a draft version of the theme: https://docs.google.com/document/d/1qylhtpuptvxgvgPaUxtzVd5vblNzeqMLDYY2B26HQcg/edit

The document is in this folder: https://drive.google.com/drive/u/0/folders/1fWbDjAYmNYft475Xv7NPb0-SPTFSB0iM