docs overhaul: render flyteidl under the /api/ path

.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

@@ -31,8 +31,8 @@ vendor/
 **/bin/
 docs/_tags/
 docs/api/flytectl
-docs/protos
 docs/api/flytekit
+docs/api/flyteidl
 docs/flytesnacks
 docs/examples
 docs/_src

docs/_static/custom.css

@@ -0,0 +1,113 @@
+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;
+}
+
+.navbar-brand img {
+    height: 70%;
+}
+
+/*
+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;
+}
+
+/* left sidebar nav width */
+.bd-sidebar-primary {
+    width: 15%;
+    min-width: 250px;
+    padding: 1rem;
+}
+
+/* make the scroll bar sleeker */
+.bd-sidebar::-webkit-scrollbar {
+    width: 3px;
+    height: 3px;
+    background: transparent;
+}
+
+.bd-sidebar::-webkit-scrollbar-thumb {
+    background: var(--pst-color-border);
+}
+
+/* make sure page content fills up the page */
+.bd-main .bd-content {
+    justify-content: left;
+}
+
+.bd-main .bd-content .bd-article-container {
+    padding: 2.5rem;
+    max-width: 75em;
+}
+
+/* aligh 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;
+}
+
+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);
+}
+
+.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

@@ -0,0 +1,10 @@
+window.addEventListener("DOMContentLoaded", function() {
+    // Select all <a> elements with class "external"
+    var externalLinks = document.querySelectorAll("a.external");
+
+    // Loop through each <a> element with class "external"
+    externalLinks.forEach(function(link) {
+        // Set the target attribute to "_blank"
+        link.setAttribute("target", "_blank");
+    });
+});

docs/api/index.md

@@ -2,6 +2,7 @@
 
 
 ::::{grid} 2
+:gutter: 2
 
 :::{grid-item-card} {octicon}`rocket` Flytekit SDK
 :link: flytekit/docs_index
@@ -10,13 +11,20 @@
 Flytekit is the main Python SDK for building workflows.
 :::
 
-:::{grid-item-card} {octicon}`workflow` Flytectl SDK
+:::{grid-item-card} {octicon}`workflow` Flytectl CLI
 :link: flytectl/docs_index
 :link-type: doc
 
 Flytectl is a Golang binary that can be installed on any platform supported by Golang.
 :::
 
+:::{grid-item-card} {octicon}`code` FlyteIDL
+:link: flyteidl/docs_index
+:link-type: doc
+
+Flyte’s core specification language.
+:::
+
 ::::
 
 ```{toctree}
@@ -25,4 +33,5 @@ Flytectl is a Golang binary that can be installed on any platform supported by G
 
 flytekit <flytekit/docs_index>
 flytectl <flytectl/docs_index>
-```
+flyteidl <flyteidl/docs_index>
+```

docs/community/contribute_docs.md

@@ -13,7 +13,7 @@ The Flyte documentation comprises the following types:
 * **API documentation:**
   * {doc}`flytekit <../api/flytekit/docs_index>`
   * {doc}`flytectl <../api/flytectl/docs_index>`
-  * {doc}`flyteidl <../reference_flyteidl>`
+  * {doc}`flyteidl <../api/flyteidl/docs_index>`
 * **{ref}`Tutorials <tutorials>`:** Longer, more advanced guides that use multiple Flyte features to solve real-world problems. Some tutorials may require extra setup, while others can only run on larger clusters.
 * **{ref}`Integrations examples <integrations>`:** These examples showcase how to use the Flyte plugins that integrate with the broader data and machine learning ecosystem.
 * **{ref}`Deployment documentation <deployment>`:** Guidance on deploying and configuring the Flyte backend.

docs/conf.py

@@ -288,6 +288,16 @@
     "flytectl/gen/flytectl_demo_teardown": "../../api/flytectl/gen/flytectl_demo_teardown",
     "flytectl/gen/flytectl_demo_exec": "../../api/flytectl/gen/flytectl_demo_exec",
     "flytectl/gen/flytectl_demo_reload": "../../api/flytectl/gen/flytectl_demo_reload",
+
+    # flyteidl
+    "reference_flyteidl": "../../api/flyteidl/docs_index.html",
+    "protos/docs/core/core": "../../api/flyteidl/docs/core/core.html",
+    "protos/docs/admin/admin": "../../api/flyteidl/docs/admin/admin.html",
+    "protos/docs/service/service": "../../api/flyteidl/docs/service/service.html",
+    "protos/docs/datacatalog/datacatalog": "../../api/flyteidl/docs/datacatalog/datacatalog.html",
+    "protos/docs/event/event": "../../api/flyteidl/docs/event/event.html",
+    "protos/docs/plugins/plugins": "../../api/flyteidl/docs/plugins/plugins.html",
+    "protos/README": "../../api/flyteidl/contributing.html",
 }
 
 
@@ -375,11 +385,31 @@
 
 html_theme_options = {
     # custom flyteorg pydata theme options
-    "github_url": "https://github.com/flyteorg/flyte",
+    # "github_url": "https://github.com/flyteorg/flyte",
+    "logo": {
+        "text": "Flyte",
+    },
+    "external_links": [
+        {"name": "Flyte", "url": "https://flyte.org"},
+    ],
     "icon_links": [
         {
             "name": "GitHub",
+            "icon": "fa-brands fa-github",
+            "type": "fontawesome",
             "url": "https://github.com/flyteorg/flyte",
+        },
+        {
+            "name": "Slack",
+            "url": "https://slack.flyte.org",
+            "icon": "fa-brands fa-slack",
+            "type": "fontawesome",
+        },
+        {
+            "name": "Flyte",
+            "url": "https://flyte.org",
+            "icon": "fa-solid fa-dragon",
+            "type": "fontawesome",
         }
     ],
     "use_edit_page_button": True,
@@ -390,9 +420,9 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = []
-# html_css_files = []
-# html_js_files = []
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_js_files = ["custom.js"]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -476,9 +506,9 @@
 tags_overview_title = "Pages by tags"
 
 # Algolia Docsearch credentials
-docsearch_app_id = os.getenv("DOCSEARCH_APP_ID")
+docsearch_app_id = "WLG0MZB58Q"
 docsearch_api_key = os.getenv("DOCSEARCH_API_KEY")
-docsearch_index_name = os.getenv("DOCSEARCH_INDEX_NAME")
+docsearch_index_name = "flyte"
 
 # -- Options for intersphinx extension ---------------------------------------
 
@@ -529,7 +559,7 @@
 
 # Pattern for replacing all ref/doc labels that point to protos/docs with /protos/docs
 PROTO_REF_PATTERN = r"([:<])(protos/docs)"
-PROTO_REF_REPLACE = r"\1/protos/docs"
+PROTO_REF_REPLACE = r"\1/api/flyteidl/docs"
 
 # These patterns are used to replace values in source files that are imported
 # from other repos.
@@ -549,7 +579,7 @@
     r"<_tags/DistributedComputing>": r"</_tags/DistributedComputing>",
     r"{ref}`bioinformatics <bioinformatics>`": r"bioinformatics",
     PROTO_REF_PATTERN: PROTO_REF_REPLACE,
-    r"/protos/docs/service/index": r"/protos/docs/service/service"
+    r"/protos/docs/service/index": r"/api/flyteidl/docs/service/service"
 }
 
 # r"<environment_setup>": r"</flytesnacks/environment_setup>",
@@ -626,8 +656,7 @@
         "name": "flyteidl",
         "source": "../flyteidl",
         "docs_path": "protos",
-        "dest": "protos",  # to stay compatible with flyteidl docs path naming
-        "cmd": ["cp", "../flyteidl/README.md", "protos/README.md"],
+        "dest": "api/flyteidl",
         "local": True,
     }
 ]