Skip to content

Commit

Permalink
chore: standardize top and bottom nav on API docs site (#16152)
Browse files Browse the repository at this point in the history
# Overview

Hacking the standard opentrons.com top and bottom nav into the docs
site.

## Test Plan and Hands on Testing

Visual inspection between [sandbox for this
branch](http://sandbox.docs.opentrons.com/docs-infra-top-nav/v2/),
opentrons.com (header/footer), and `edge` [sandbox with Public
Sans](http://sandbox.docs.opentrons.com/edge/v2/) (body).

All on macOS. Mostly in Safari. Also tested Chrome.

## Changelog


![CSS](https://github.com/user-attachments/assets/38db406a-3dbd-4221-9d36-27ca3a78225e)

- Include saved versions of our `remote-nav.html` and
`remote-footer.html` files in the docs layout.
- Rescope a bunch of docs CSS rules so they aren't overridden by the
included HTML.
- Recapitulate a bunch of the header/footer rules so they aren't
overridden by the docs template.
- Adjust the height of the main body container to account for the
shorter header.
- Hide the 🔍 button in the main nav so users don't use that search in an
attempt to only search the PAPI docs.

### Follow up tasks
For another PR.
- Replicate on v1 docs
- Replicate on OT-One docs
- Replicate on hardware docs or remove hardware docs

## Review requests

- Do I know what I'm doing at all? Is this approach — saving and
importing static versions of the navs — the best we can do? As far as I
can tell, Sphinx can't fetch and include remote resources. But maybe we
could do it as part of `make -C api docs` so these don't get frozen in
time again?
- Is there any way to eliminate the brief appearance of the subnavs on
page load?
- Plz check <s>Chrome</s> Windows.

## Risk assessment

medium. there could be whole parts of the docs site that i've broken and
didn't notice.
  • Loading branch information
ecormany authored Sep 26, 2024
1 parent 7100b00 commit 18fda28
Show file tree
Hide file tree
Showing 4 changed files with 1,461 additions and 1,144 deletions.
173 changes: 148 additions & 25 deletions api/docs/static/override_sphinx.css
Original file line number Diff line number Diff line change
@@ -1,26 +1,80 @@
@import url('https://fonts.googleapis.com/css?family=Public+Sans:300,400,400i,600,700');
@import url('https://fonts.googleapis.com/css2?family=Reddit+Mono:[email protected]&display=swap');

/* OT NAV */
/* OT TOP NAV */

body {
padding: 0;
margin: 0;
font-family: "Public Sans", "sans-serif";
}

.highlight-none, .mi, .literal {
color: #048f85;
/* restate button styling */
.text-brand-blue:hover {
--tw-text-opacity: 1;
color: rgb(0 108 250 / var(--tw-text-opacity));
}

.text-white:hover {
--tw-text-opacity: 1;
color: rgb(255 255 255 / var(--tw-text-opacity));
}

/* hack out search button */

div.flex.gap-4 div.text-white.flex.items-center.h-full > button {
display: none;
}

/* use Akko from docs site instead of from main site */
header a.button-sm {
font-family: "AkkoPro-Regular", "Akko Pro", "Open Sans", sans-serif !important;
}

/* OT FOOTER */

footer {
padding: 0;
}

.footer-app-button:hover {
color: #E8E9EA;
}

/* restate newsletter form styling */

footer input.hs-input {
margin: 0;
max-width: 100%;
width: 100%;
height: 42px;
padding-left: 1rem;
padding-right: 1rem;
padding-top: 0.5rem;
padding-bottom: 0.5rem;
font-size: 1rem;
--tw-text-opacity: 1;
color: rgb(112 112 117 / var(--tw-text-opacity));
}

footer .hs_submit input {
height: 40px;
min-width: 100% !important;
width: 100% !important;
}

/* DOCS */
div.document .highlight-none, .mi, .literal {
color: #048f85;
}

div.document {
padding-top: 150px;
padding-top: 96px;
margin-top: 0;
font-family: "Public Sans", "sans-serif";
}

div.document [id] {
scroll-margin-top: 150px;
scroll-margin-top: 110px;
}

@media only screen and (min-device-width: 768px) and (min-width: 768px) and (max-width: 1023px) {
Expand All @@ -34,31 +88,62 @@ div.document [id] {
}
}

div.body p {
div.document p {
line-height: 20pt;
font-family: "Public Sans", "sans-serif";
}

pre, tt, code {
div.document section > p,
div.document dl p {
margin: 1em 0;
}

div.document pre,
div.document tt,
div.document code {
font-size: 0.9em;
font-family: "Reddit Mono", "Consolas", "Lucida Console", monospace;
}

/* classes for API Reference docstring signatures */
.sig, .sig-name, code.descname, .sig-prename, .optional, .sig-paren {
div.document dl {
margin-bottom: 15px;
}

/* API Reference */
div.document .sig,
div.document .sig-name,
div.document code.descname,
div.document .sig-prename,
div.document .optional,
div.document .sig-paren {
font-size: 1em;
font-family: "Reddit Mono", "Consolas", "Lucida Console", monospace;
}

div.body h1 {
div.document dt.field-even,
div.document dt.field-odd {
margin-top: 1em;
line-height: 20pt;
}

div.document dd ul {
margin-top: 1em;
}

span.colon {
display: none;
}

/* all article pages */

div.document h1 {
margin-top: 0;
margin-bottom: 0;
padding-top: 0;
font-size: 2.4em;
font-size: 2em;
min-height: 78px;
}

div.body h1 + p {
div.document h1 + p {
padding-top: 24px;
}

Expand All @@ -70,6 +155,19 @@ div.documentwrapper {
float: none;
}

div.body {
padding-top: 1rem;
}

a:hover {
color: inherit;
text-decoration: inherit;
}

div.body a {
color: #006FFF;
}

/* Don't allow inline items try to clear themselves below the sidebar */
pre, div[class*="highlight-"], blockquote, blockquote::after, div.admonition::after {
clear: none;
Expand All @@ -78,14 +176,14 @@ pre, div[class*="highlight-"], blockquote, blockquote::after, div.admonition::af
/* Sticky, scrolling sidebar. Height calc leaves room for header. */
div.sphinxsidebar {
position: sticky;
top: 150px;
top: 96px;
align-self: flex-start;
max-height: calc(100vh - 150px);
max-height: calc(100vh - 96px);
overflow-y: auto;
}

div.sphinxsidebarwrapper {
padding-top: 6px;
padding-top: 1rem;
}

/* Hide the redundant 'description' tagline */
Expand All @@ -98,13 +196,24 @@ div.sphinxsidebar h3,
div.sphinxsidebar h4,
div.sphinxsidebar h5,
div.sphinxsidebar h6,
div.body h2,
div.body h3,
div.body h4,
div.body h5 {
font-family: "Public Sans", "sans-serif";
div.document h2,
div.document h3,
div.document h4,
div.document h5 {
font-family: "Public Sans", "sans-serif" !important;
text-transform: none !important;
letter-spacing: 0 !important;
}

/* hide the word "Navigation" because people know what links are */
div.sphinxsidebarwrapper > h3 {
display: none;
}

/* restate header sizes to avoid conflict from inline style in footer */
div.document h3 { font-size: 150% !important; }
div.document h4 { font-size: 130% !important; }

/* Links need an extra two pixels of padding to compensate between body font height
being 1em and code font height being 0.9em */
a.reference {
Expand Down Expand Up @@ -209,12 +318,20 @@ div.body p.caption {
font-size: 22px;
}

ul {
/* margin-left: 0; */
div.body ul, div.body ol {
margin: 10px 0 10px 30px;
font-family: "Public Sans", "sans-serif";
}

ul ul {
div.body ul {
list-style-type: disc;
}

div.body ul p, div.body ol p {
margin-bottom: 0;
}

div.body ul ul {
list-style-type: circle;
margin-left: 30px;
font-family: "Public Sans", "sans-serif";
Expand Down Expand Up @@ -280,3 +397,9 @@ div.warning {
background-color: #f7e0e0;
border: none;
}

/* Tabs also in Public Sans */

.sphinx-tabs-tab {
font-family: "Public Sans", "sans-serif" !important;
}
Loading

0 comments on commit 18fda28

Please sign in to comment.