Docs: Eng / Design Improvements for the 2024

[dgmccart]

Running list of design / eng improvements for the docs sites:

Theme / Figures

• Update theme to sphinx-immaterial Change doc site theme to sphinx-immaterial #889(Designs for mkdocs version of this theme)
• Add data schema graphic to the site
• Enable dark mode
• Set up method for changing figures for dark mode
• Specify alignment of figures on the site (e.g. center justified)

Navigation

• Add hierarchy to the table of contents (e.g. tutorials landing page with sub-pages) (jump-to-navigation) - break into 2 items
• Fix anchor linking so that the section header isn't cuts off when the hyperlink is clicked) Links to "section" headers don't scroll to the right position #888
• Switch hyperlinks to internal links docs: Update hyperlinks to internal links on docsite #1109
• Update link locations on the Portal Update link locations on Portal UI #1111
• Function to open accordions from links - needs exploration Function for opening accordions from links #772
• Accordion / admonition styling
• Implement cards / tiles design element (e.g. see below) - comes for free from site theme docs: Reorganize pages, update homepage content, and implement tiles on the homepage #1188

• Add indicator to the sidebar of where you are when scrolling the page (e.g. see below where the right side bar uses grey or black coloring to indicate where the user is on the page)

API Reference

• Improve data model graphic (e.g. create an interactive data model graphic) P0 is address this issue
• Custom examples of inherited functions in API documentation Allow customized examples for common attributes/methods #890 - needs exploration
• Improve styling and navigation of API docs following the update to sphinx-immaterial theme
• Versioned docs
• Syntax highlighting in code blocks for python and JSON
• Alphabetize API reference Python API documentation not in alphabetical order #944

---

Potential content for 2025:

• Further improving styling of API docs

[dgmccart]

Start with updating theme, and then move on the API study recommendations related items.