From dbf654fc8139926e086940af1ab232a2eea3fcb8 Mon Sep 17 00:00:00 2001 From: pdmurray Date: Thu, 4 Jan 2024 13:07:51 -0800 Subject: [PATCH] [Doc] Theme revamp: styling changes Signed-off-by: pdmurray --- doc/source/_static/css/custom.css | 2 + .../_static/css/{splash.css => index.css} | 2 +- doc/source/_static/js/index.js | 52 ++ doc/source/_static/js/splash.js | 48 -- .../{splash.html => _templates/index.html} | 486 +++++++++--------- doc/source/conf.py | 9 +- doc/source/custom_directives.py | 10 + doc/source/index.rst | 3 - 8 files changed, 313 insertions(+), 299 deletions(-) rename doc/source/_static/css/{splash.css => index.css} (99%) create mode 100644 doc/source/_static/js/index.js delete mode 100644 doc/source/_static/js/splash.js rename doc/source/{splash.html => _templates/index.html} (60%) diff --git a/doc/source/_static/css/custom.css b/doc/source/_static/css/custom.css index 983f9d7fb4cb..a3a8dd18e0e9 100644 --- a/doc/source/_static/css/custom.css +++ b/doc/source/_static/css/custom.css @@ -25,6 +25,7 @@ html[data-theme='dark'] { --pst-color-text-muted: #b3b9c4; --heading-color: #ffffff; --base-pygments-code-color: #cccccc; + --pst-color-link-hover: #cce0ff; } html[data-theme='light'] { @@ -33,6 +34,7 @@ html[data-theme='light'] { --pst-color-text-muted: #454f59; --heading-color: #161a1d; --base-pygments-code-color: #cccccc; + --pst-color-link-hover: #09326c; } nav.bd-links li > a:hover { diff --git a/doc/source/_static/css/splash.css b/doc/source/_static/css/index.css similarity index 99% rename from doc/source/_static/css/splash.css rename to doc/source/_static/css/index.css index bd1e3e89de7d..0e388e4b88c7 100644 --- a/doc/source/_static/css/splash.css +++ b/doc/source/_static/css/index.css @@ -62,7 +62,7 @@ .tab-pane pre { margin: 0; - padding: 0; + padding: 0.5em 1em; max-height: 252px; overflow-y: auto; animation: fadeEffect 1s; /* Fading effect takes 1 second */ diff --git a/doc/source/_static/js/index.js b/doc/source/_static/js/index.js new file mode 100644 index 000000000000..8b6b0e3d7f9e --- /dev/null +++ b/doc/source/_static/js/index.js @@ -0,0 +1,52 @@ +function animateTabs() { + const tabs = Array.from(document.getElementById('v-pills-tab').children); + const contentTabs = Array.from( + document.getElementById('v-pills-tabContent').children, + ); + + tabs.forEach((item, index) => { + item.onclick = () => { + tabs.forEach((tab, i) => { + if (i === index) { + item.classList.add('active'); + } else { + tab.classList.remove('active'); + } + }); + contentTabs.forEach((tab, i) => { + if (i === index) { + tab.classList.add('active', 'show'); + } else { + tab.classList.remove('active', 'show'); + } + }); + }; + }); +} + +function updateHighlight() { + const {theme} = document.documentElement.dataset; + ['dark', 'light'].forEach((title) => { + const stylesheet = document.querySelector(`link[title="${title}"]`); + if (title === theme) { + stylesheet.removeAttribute('disabled'); + } else { + stylesheet.setAttribute('disabled', 'disabled'); + } + }); +} + +function setHighlightListener() { + const observer = new MutationObserver((mutations) => updateHighlight()); + observer.observe(document.documentElement, { + attributes: true, + attributeFilter: ['data-theme'], + }); +} + +document.addEventListener('DOMContentLoaded', animateTabs); +document.addEventListener('DOMContentLoaded', () => { + hljs.highlightAll(); + updateHighlight(); +}); +document.addEventListener('DOMContentLoaded', setHighlightListener); diff --git a/doc/source/_static/js/splash.js b/doc/source/_static/js/splash.js deleted file mode 100644 index b517b9575080..000000000000 --- a/doc/source/_static/js/splash.js +++ /dev/null @@ -1,48 +0,0 @@ -function animateTabs() { - const tabs = Array.from(document.getElementById("v-pills-tab").children) - const contentTabs = Array.from(document.getElementById("v-pills-tabContent").children) - - tabs.forEach((item, index) => { - item.onclick = () => { - tabs.forEach((tab, i) => { - if (i === index) { - item.classList.add('active') - } else { - tab.classList.remove('active') - } - }) - contentTabs.forEach((tab, i) => { - if (i === index) { - tab.classList.add('active', 'show') - } else { - tab.classList.remove('active', 'show') - } - }) - } - }) -} - -function updateHighlight() { - const { theme } = document.documentElement.dataset; - ["dark", "light"].forEach(title => { - const stylesheet = document.querySelector(`link[title="${title}"]`) - if (title === theme) { - stylesheet.removeAttribute("disabled") - } else { - stylesheet.setAttribute("disabled", "disabled") - } - }) -} - - -function setHighlightListener() { - const observer = new MutationObserver(mutations => updateHighlight()) - observer.observe(document.documentElement, {attributes: true, attributeFilter: ['data-theme']}); -} - -document.addEventListener("DOMContentLoaded", animateTabs) -document.addEventListener("DOMContentLoaded", () => { - hljs.highlightAll() - updateHighlight() -}) -document.addEventListener("DOMContentLoaded", setHighlightListener) diff --git a/doc/source/splash.html b/doc/source/_templates/index.html similarity index 60% rename from doc/source/splash.html rename to doc/source/_templates/index.html index 77079d2ac5cb..42a496abcd1b 100644 --- a/doc/source/splash.html +++ b/doc/source/_templates/index.html @@ -1,128 +1,128 @@ +{% extends "!pydata_sphinx_theme/layout.html" %} {% block body %} Welcome to Ray! -
-
-
-
-

Welcome to Ray!

-

- Ray is an open-source unified framework for scaling AI and Python - applications. It provides the compute layer for parallel processing so - that you don’t need to be a distributed systems expert. -

-
- - - - - - - - - -
-
-
- +
+
+
+

Welcome to Ray!

+

+ Ray is an open-source unified framework for scaling AI and Python + applications. It provides the compute layer for parallel processing so + that you don’t need to be a distributed systems expert. +

+
+ + + + + + + + +
+
+ +
-

Scaling with Ray

+
+

Scaling with Ray

-
-
- -
-
-
+
+
+
+
+
+ +
+ {{ pygments_highlight_python(''' from typing import Dict import numpy as np @@ -144,9 +144,9 @@

Scaling with Ray

predictions = self.model( list(batch["data"]), max_length=20, num_return_sequences=1) # `predictions` is a list of length-one lists. For example: - # [[{'generated_text': 'output_1'}], ..., [{'generated_text': 'output_2'}]] + # [[{"generated_text": "output_1"}], ..., [{"generated_text": "output_2"}]] # Modify the output to get it into the following format instead: - # ['output_1', 'output_2'] + # ["output_1", "output_2"] batch["output"] = [sequences[0]["generated_text"] for sequences in predictions] return batch @@ -157,34 +157,33 @@

Scaling with Ray

predictions = ds.map_batches(HuggingFacePredictor, compute=scale) # Step 4: Show one prediction output. predictions.show(limit=1) - - -
-
- Learn more - | - API references -
-
- - - Open in Github - + ''') }} +
+
+ Learn more + | + API references +
+
+ + + Open in Github + +
-
-
- 
-          
+        
+        

+        {{ pygments_highlight_python('''
 from ray.train import ScalingConfig
 from ray.train.torch import TorchTrainer
 
@@ -195,7 +194,7 @@ 
Scaling with Ray

     for epoch in range(num_epochs):
         ...  # model training logic
 
-# Step 2: setup Ray's PyTorch Trainer to run on 32 GPUs
+# Step 2: setup Ray\'s PyTorch Trainer to run on 32 GPUs
 trainer = TorchTrainer(
     train_loop_per_worker=train_loop_per_worker,
     scaling_config=ScalingConfig(num_workers=32, use_gpu=True),
@@ -204,42 +203,41 @@ 
Scaling with Ray

 
 # Step 3: run distributed model training on 32 GPUs
 result = trainer.fit()
-          
-
-
-
- Learn more - | - API references -
-
- - - Open in colab - + ''') }} +
+
+ Learn more + | + API references +
+
+ + + Open in colab + +
-
-
- 
-          
+        
+        

+        {{ pygments_highlight_python('''
 from ray import tune
 from ray.train import ScalingConfig
 from ray.train.lightgbm import LightGBMTrainer
 
 train_dataset, eval_dataset = ...
 
-# Step 1: setup Ray's LightGBM Trainer to train on 64 CPUs
+# Step 1: setup Ray\'s LightGBM Trainer to train on 64 CPUs
 trainer = LightGBMTrainer(
     ...
     scaling_config=ScalingConfig(num_workers=64),
@@ -255,36 +253,34 @@ 
Scaling with Ray

 
 # Step 3: run distributed HPO with 1000 trials; each trial runs on 64 CPUs
 result_grid = tuner.fit()
-
-          
-
-
-
- Learn more - | - API references -
-
- - - Open in Github - + ''') }} +
+
+ Learn more + | + API references +
+
+ + + Open in Github + +
-
-
- 
-          
+        
+        

+        {{ pygments_highlight_python('''
 from io import BytesIO
 from fastapi import FastAPI
 from fastapi.responses import Response
@@ -344,34 +340,35 @@ 
Scaling with Ray

 
 
 entrypoint = APIIngress.bind(StableDiffusionV2.bind())
-          
-
-
-
- Learn more - | - API references -
-
- - - Open in Github - + ''') }} +
+
+ Learn more + | + + API references + +
+
+ + + Open in Github + +
-
-
- 
-          
+        
+        

+        {{ pygments_highlight_python('''
 from ray.rllib.algorithms.ppo import PPOConfig
 
 # Step 1: configure PPO to run 64 parallel workers to collect samples from the env.
@@ -391,29 +388,31 @@ 
Scaling with Ray

     print(ppo_algo.train())
 
 ppo_algo.evaluate()
-
-
-
- Learn more - | - - API references - -
-
- - - Open in Github - + ''') }} +
+
+ Learn more + | + + API references + +
+
+ + + Open in Github + +
+
Contribute to Ray
+{{ super() }} {% endblock %} diff --git a/doc/source/conf.py b/doc/source/conf.py index c130c8068a22..ce35f4328b41 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -406,12 +406,13 @@ def add_custom_assets( See documentation on Sphinx Core Events for more information: https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events """ + if pagename == "index": + app.add_css_file("css/index.css") + app.add_js_file("js/index.js") + return "index.html" # Use the special index.html template for this page + if pagename == "train/train": app.add_css_file("css/ray-train.css") - elif pagename == "index": - # CSS for HTML part of index.html - app.add_css_file("css/splash.css") - app.add_js_file("js/splash.js") elif pagename == "ray-overview/examples": # Example gallery app.add_css_file("css/examples.css") diff --git a/doc/source/custom_directives.py b/doc/source/custom_directives.py index 00fb37784d8a..a2da1bbb9967 100644 --- a/doc/source/custom_directives.py +++ b/doc/source/custom_directives.py @@ -19,6 +19,11 @@ from functools import lru_cache from pydata_sphinx_theme.toctree import add_collapse_checkboxes +from pygments import highlight +from pygments.lexers import PythonLexer +from pygments.formatters import HtmlFormatter + + logger = logging.getLogger(__name__) __all__ = [ @@ -435,6 +440,11 @@ def render_header_nodes( ) context["render_header_nav_links"] = render_header_nav_links + # Update the HTML page context with a few extra utilities. + context["pygments_highlight_python"] = lambda code: highlight( + code, PythonLexer(), HtmlFormatter() + ) + def update_hrefs(input_soup: bs4.BeautifulSoup, n_levels_deep=0): soup = copy.copy(input_soup) diff --git a/doc/source/index.rst b/doc/source/index.rst index 1a8ba42fc0f0..cf1db0e55e07 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -23,6 +23,3 @@ Developer Guides Glossary Security - -.. raw:: html - :file: splash.html