Switch to PyData theme
Opened this issue · 7 comments
- 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 (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
As of quite recently, JupyterBook and dependencies have been refreshed: https://jupyterbook.org/reference/_changelog.html#v0-8-0-2020-09-01
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)
A reminder that I'll need to update the crawler for the new theme: open-contracting/ocds-index#6
Done
Comment moved to #36 (comment)
A follow-up issue will be to restore a good print stylesheet, and test its output with make pdf.
Created #44
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.
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