From 18fda284d8c1e62657d5919bc06d7cf511849b6d Mon Sep 17 00:00:00 2001 From: Ed Cormany Date: Thu, 26 Sep 2024 11:55:47 -0400 Subject: [PATCH] chore: standardize top and bottom nav on API docs site (#16152) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # 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 Chrome Windows. ## Risk assessment medium. there could be whole parts of the docs site that i've broken and didn't notice. --- api/docs/static/override_sphinx.css | 173 +++- api/docs/templates/v2/layout.html | 1122 +--------------------- api/docs/templates/v2/remote-footer.html | 345 +++++++ api/docs/templates/v2/remote-nav.html | 965 +++++++++++++++++++ 4 files changed, 1461 insertions(+), 1144 deletions(-) create mode 100644 api/docs/templates/v2/remote-footer.html create mode 100644 api/docs/templates/v2/remote-nav.html diff --git a/api/docs/static/override_sphinx.css b/api/docs/static/override_sphinx.css index 10a1d091b94..8af01be9c04 100644 --- a/api/docs/static/override_sphinx.css +++ b/api/docs/static/override_sphinx.css @@ -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:wght@200..900&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) { @@ -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; } @@ -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; @@ -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 */ @@ -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 { @@ -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"; @@ -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; +} \ No newline at end of file diff --git a/api/docs/templates/v2/layout.html b/api/docs/templates/v2/layout.html index fbc6e860eaf..fd795d94c38 100644 --- a/api/docs/templates/v2/layout.html +++ b/api/docs/templates/v2/layout.html @@ -31,1015 +31,7 @@ {%- if theme_fixed_sidebar|lower == 'true' %} @@ -1061,116 +53,8 @@ {%- else %} {{ super() }} {%- endif %} {%- endblock %} {%- block footer %} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/api/docs/templates/v2/remote-nav.html b/api/docs/templates/v2/remote-nav.html new file mode 100644 index 00000000000..3dbd3c18dca --- /dev/null +++ b/api/docs/templates/v2/remote-nav.html @@ -0,0 +1,965 @@ + + + + + + + + + + + +Remote Nav - Opentrons + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+
+
+ + + +
+ + + Opentrons logo + + +
+ +
+
+ + + +
+ + +
+
+ Cancel +
+
+
+
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+ +
+
+ +
+ + + Protocol Designer + Protocol Library + Python API + Labware Library + GitHub + OT App +
+
+
+ +
+
+ Schedule a Demo + Contact Sales +
+ +
+ + + + + + +
+ + +
+
+
+
+ + + + +