Flyte docs overhaul (phase 1)

.github/workflows/tests.yml

@@ -69,6 +69,9 @@ jobs:
       - name: Build the documentation
         working-directory: ${{ github.workspace }}/flyte
         shell: bash -el {0}
+        env:
+          # this is a fake key for algolia docsearch to make docs build process pass
+          DOCSEARCH_API_KEY: fake_docsearch_api_key
         run: |
           conda activate monodocs-env
           make docs

.gitignore

@@ -30,12 +30,11 @@ vendor/
 /docker/sandbox-bundled/images/tar
 **/bin/
 docs/_tags/
-docs/flytectl
-docs/protos
-docs/flytekit
+docs/api/flytectl
+docs/api/flytekit
+docs/api/flyteidl
 docs/flytesnacks
 docs/examples
 docs/_src
 docs/_projects
-docs/api
 docs/tests

docs/Makefile

@@ -20,4 +20,4 @@ help:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 clean:
-	rm -rf _build _src _tags api flytectl flytekit flytesnacks protos examples tests _projects
+	rm -rf _build _src _tags api/flytectl api/flytekit flytesnacks protos examples tests _projects

docs/_static/custom.css

@@ -1,49 +1,113 @@
-.getting-started-panels div.card-body {
-    padding: 0;
+html[data-theme=light], html[data-theme=dark] {
+    --pst-color-primary: #7652A2;
+    --pst-color-link: #7652A2;
+    --pst-color-link-hover: #7652A2;
+}
+
+
+/* Styling for page layout */
+.bd-page-width {
+    max-width: 100%;
+}
+
+/* style the main title logo */
+.navbar-brand:hover, .navbar-brand:visited:hover {
+    text-decoration: none;
 }
 
-.getting-started-panels a.btn-primary {
-    color: white !important;
-    background-color: var(--color-link);
-    border-color: var(--color-link);
+.navbar-brand img {
+    height: 70%;
 }
 
-.getting-started-panels a.btn-outline-primary {
-    color: white !important;
-    background-color: var(--color-link);
-    opacity: 0.5;
-    border-color: var(--color-link);
+/*
+Center the main page content only when the sidebar has the .hide-on-wide
+class, which is only on the root page
+*/
+.bd-sidebar.hide-on-wide + main.bd-main .bd-content {
+    justify-content: center;
 }
 
-html .tabbed-set > label {
-    color: var(--color-foreground-border);
+/* left sidebar nav width */
+.bd-sidebar-primary {
+    width: 15%;
+    min-width: 250px;
+    padding: 1rem;
 }
 
-html .tabbed-set > input:checked + label {
-    border-color: var(--color-link);
-    color: var(--color-link);
+/* make the scroll bar sleeker */
+.bd-sidebar::-webkit-scrollbar {
+    width: 3px;
+    height: 3px;
+    background: transparent;
 }
 
-html .tabbed-set > label:hover {
-    color: var(--color-link);
+.bd-sidebar::-webkit-scrollbar-thumb {
+    background: var(--pst-color-border);
 }
 
-html .tabbed-content {
-    box-shadow: 0 -.0625rem var(--color-background-border),0 .0625rem var(--color-background-border);
+/* make sure page content fills up the page */
+.bd-main .bd-content {
+    justify-content: left;
 }
 
-table {
-    width: 100%;
+.bd-main .bd-content .bd-article-container {
+    padding: 2.5rem;
+    max-width: 75em;
+}
+
+/* align navbar items with the sidebar */
+.bd-header .navbar-header-items__start {
+    width: 15%;
+    min-width: 250px;
+}
+
+/* styles for the main page subtitle and badges */
+div.sd-card.sd-shadow-sm.subtitle-and-badges {
+    border: none;
     box-shadow: none !important;
 }
 
-.sidebar-container, .toc-drawer {
-    width: 22em;
-    padding-right: 0;
+div.subtitle-and-badges .sd-card-body {
+    padding: 0;
+}
+
+div.subtitle-and-badges .sd-card-title {
+    color: #808080;
+    font-weight: 350 !important;
+    font-size: 25px;
+    padding-top: 10px;
+    padding-bottom: 10px;
+}
+
+div.subtitle-and-badges a {
+    text-decoration: none;
+}
+
+div.subtitle-and-badges a img {
+    margin: 2px 0;
+}
+
+/* update table hover color to neutral color */
+.table tbody tr:hover {
+    background-color: var(--pst-color-table-inner-border);
+}
+
+/* custom footer style */
+div.custom-footer {
+    text-align: center;
+    background-color: var(--pst-color-surface);
+    padding: 15px 0;
+    color: var(--pst-color-text-muted);
+}
+
+/* anchor link hover style */
+a:hover,
+nav.bd-links li>a:active,
+nav.bd-links li>a:hover,
+.bd-header ul.navbar-nav>li.nav-item>.nav-link:hover {
+    color: var(--pst-color-primary);
 }
 
-@media (max-width: 82em) {
-    .toc-drawer {
-        right: -22em;
-    }
+.bd-header ul.navbar-nav>li.nav-item>.nav-link:hover:before {
+    border-bottom: max(3px, .1875rem, .12em) solid var(--pst-color-primary);
 }

docs/_static/custom.js

@@ -1,4 +1,3 @@
-// Add event listener for DOMContentLoaded event
 window.addEventListener("DOMContentLoaded", function() {
     // Select all <a> elements with class "external"
     var externalLinks = document.querySelectorAll("a.external");
@@ -9,103 +8,3 @@ window.addEventListener("DOMContentLoaded", function() {
         link.setAttribute("target", "_blank");
     });
 });
-
-// This function was adapted from pydata-sphinx-theme
-// https://github.com/pydata/pydata-sphinx-theme/blob/733d9f3264020c8a5bd3dde38f3ee3e5cdb2979a/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js#L133-L175
-function scrollToActive() {
-    // If the docs nav doesn't exist, do nothing (e.g., on search page)
-    if (!document.querySelector(".sidebar-scroll")) {
-      return;
-    }
-
-    var sidebar = document.querySelector("div.sidebar-scroll");
-
-    // Remember the sidebar scroll position between page loads
-    // Inspired on source of revealjs.com
-    let storedScrollTop = parseInt(
-      sessionStorage.getItem("sidebar-scroll-top"),
-      10
-    );
-
-    if (!isNaN(storedScrollTop)) {
-      // If we've got a saved scroll position, just use that
-      sidebar.scrollTop = storedScrollTop;
-      console.log("Scrolled sidebar using stored browser position...");
-    } else {
-      // Otherwise, calculate a position to scroll to based on the lowest `active` link
-      var sidebarNav = document.querySelector(".sidebar-scroll");
-      var active_pages = sidebarNav.querySelectorAll(".current-page");
-      if (active_pages.length > 0) {
-        // Use the last active page as the offset since it's the page we're on
-        var latest_active = active_pages[active_pages.length - 1];
-        var offset =
-          latest_active.getBoundingClientRect().y -
-          sidebar.getBoundingClientRect().y;
-        // Only scroll the navbar if the active link is lower than 50% of the page
-        if (latest_active.getBoundingClientRect().y > window.innerHeight * 0.5) {
-          let buffer = 0.25; // Buffer so we have some space above the scrolled item
-          sidebar.scrollTop = offset - sidebar.clientHeight * buffer;
-          console.log("Scrolled sidebar using last active link...");
-        }
-      }
-    }
-
-    setTimeout(function() {
-      // sidebar is hidden by default, so we need to make it visible
-      // after scrolling. This prevents the scrollbar from jittering when
-      // the page loads.
-      console.log("Sidebar is now visible...")
-      sidebar.style.visibility = "visible";
-    }, 10);
-
-    // Store the sidebar scroll position
-    window.addEventListener("beforeunload", () => {
-      sessionStorage.setItem("sidebar-scroll-top", sidebar.scrollTop);
-    });
-}
-
-
-function setHtmlDataTheme() {
-  // Set theme at the root html element
-  setTimeout(() => {
-    const theme = document.body.dataset.theme;
-    const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
-
-    if (theme === "auto") {
-      document.documentElement.dataset.theme = prefersDark ? "dark" : "light";
-    } else {
-      document.documentElement.dataset.theme = theme;
-    }
-  }, 10)
-}
-
-
-function setupAlgoliaTheme() {
-  // To get darkmode in the algolia search modal, we need to set the theme in
-  // the root html element. This function propagates the theme set by furo
-  // that's set in the body element.
-  const buttons = document.getElementsByClassName("theme-toggle");
-
-  // set for initial document load
-  setHtmlDataTheme();
-
-  // listen for when theme button is clicked.
-  Array.from(buttons).forEach((btn) => {
-    btn.addEventListener("click", setHtmlDataTheme);
-  });
-}
-
-
-function main() {
-  scrollToActive()
-  setupAlgoliaTheme()
-}
-
-document.addEventListener('DOMContentLoaded', main);
-window.addEventListener('keydown', (event) => {
-  if (event.code === "Escape") {
-    // make sure to prevent default behavior with escape key so that algolia
-    // modal can be closed properly.
-    event.preventDefault();
-  }
-});