Skip to content

Commit

Permalink
docs overhaul: render flyteidl under the /api/ path (#5802)
Browse files Browse the repository at this point in the history
* fix flyteidl structure so it renders under /api/

Signed-off-by: Niels Bantilan <[email protected]>

* do not check in flyteidl docs

Signed-off-by: Niels Bantilan <[email protected]>

* update gitignore and unneeded conf

Signed-off-by: Niels Bantilan <[email protected]>

* add mock DOCSEARCH_API_KEY to docs test ci

Signed-off-by: Niels Bantilan <[email protected]>

* add css styling (#5803)

* add css styling

Signed-off-by: Niels Bantilan <[email protected]>

* update logo height

Signed-off-by: Niels Bantilan <[email protected]>

---------

Signed-off-by: Niels Bantilan <[email protected]>

---------

Signed-off-by: Niels Bantilan <[email protected]>
  • Loading branch information
cosmicBboy authored Oct 3, 2024
1 parent 97c2e48 commit 0893806
Show file tree
Hide file tree
Showing 14 changed files with 293 additions and 142 deletions.
3 changes: 3 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
113 changes: 113 additions & 0 deletions docs/_static/custom.css
Original file line number Diff line number Diff line change
@@ -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 */

Check failure on line 58 in docs/_static/custom.css

View workflow job for this annotation

GitHub Actions / Check for spelling errors

aligh ==> align, alight
.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);
}
10 changes: 10 additions & 0 deletions docs/_static/custom.js
Original file line number Diff line number Diff line change
@@ -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");
});
});
6 changes: 4 additions & 2 deletions docs/_templates/layout.html

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

13 changes: 11 additions & 2 deletions docs/api/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@


::::{grid} 2
:gutter: 2

:::{grid-item-card} {octicon}`rocket` Flytekit SDK
:link: flytekit/docs_index
Expand All @@ -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}
Expand All @@ -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>
```
2 changes: 1 addition & 1 deletion docs/community/contribute_docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,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.
Expand Down
49 changes: 39 additions & 10 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
}


Expand Down Expand Up @@ -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,
Expand All @@ -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.
Expand Down Expand Up @@ -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 ---------------------------------------

Expand Down Expand Up @@ -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.
Expand All @@ -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>",
Expand Down Expand Up @@ -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,
}
]
Expand Down
Loading

0 comments on commit 0893806

Please sign in to comment.