diff --git a/.readthedocs.yaml b/.readthedocs.yaml index f891a96290cc..fb0bdb55d3d8 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -9,7 +9,7 @@ version: 2 build: os: ubuntu-22.04 tools: - python: "3.10" + python: "3.11" # Build documentation in the docs/ directory with Sphinx sphinx: diff --git a/doc/Makefile b/doc/Makefile index b60cf1ffe4c4..0edf0ce6eb11 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = -a -E +SPHINXOPTS = -a -E -W -j auto SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build diff --git a/doc/requirements-doc.txt b/doc/requirements-doc.txt index 5a5c37e359f5..7a585c72cd6f 100644 --- a/doc/requirements-doc.txt +++ b/doc/requirements-doc.txt @@ -1,35 +1,32 @@ # Production requirements. This is what readthedocs.com picks up -ray -watchfiles # Required because sphinx-click doesn't support mocking +git+https://github.com/ray-project/tune-sklearn@master#tune-sklearn +watchfiles==0.20.0 # Required because sphinx-click doesn't support mocking # Syntax highlighting -Pygments==2.13.0 +Pygments==2.16.1 # Sphinx -sphinx==4.3.2 -sphinx-click==3.0.2 -sphinx-copybutton==0.4.0 +sphinx==7.2.6 +sphinx-click==5.0.1 +sphinx-copybutton==0.5.2 sphinxemoji==0.2.0 -sphinx-jsonschema==1.17.2 -sphinx-version-warning==1.1.2 -sphinx-book-theme==0.3.3 -sphinx-external-toc==0.2.4 -sphinx-sitemap==2.2.0 +sphinx-jsonschema==1.19.1 +sphinx-sitemap==2.5.1 sphinxcontrib-redoc==1.6.0 -sphinx-tabs==3.4.0 sphinx-remove-toctrees==0.0.3 -autodoc_pydantic==1.6.1 -sphinx_design==0.4.1 +autodoc_pydantic==1.9.0 +sphinx_design==0.5.0 +pydata-sphinx-theme==0.14.1 -pydantic<2 # Pydantic is required by autodoc_pydantic, but must be <2 for ray +pydantic<2 # MyST -myst-parser==0.15.2 -myst-nb==0.13.1 +myst-parser==2.0.0 # Needed to parse markdown +myst-nb==1.0.0rc0 # Most recent version of myst-nb; pin when new release is made # Jupyter conversion -jupytext==1.13.6 +jupytext==1.15.2 # Pin urllib to avoid downstream ssl incompatibility issues urllib3 < 1.27 diff --git a/doc/source/_toc.yml b/doc/source/_toc.yml deleted file mode 100644 index 1977d90409d8..000000000000 --- a/doc/source/_toc.yml +++ /dev/null @@ -1,398 +0,0 @@ -format: jb-book -root: index -parts: - - caption: Ray - chapters: - - file: ray-overview/index - title: "Overview" - - file: ray-overview/getting-started - title: "Getting Started" - - file: ray-overview/installation - title: "Installation" - - file: ray-overview/use-cases - title: "Use Cases" - sections: - - file: ray-air/getting-started - - - file: ray-overview/examples - title: "Example Gallery" - - file: ray-overview/ray-libraries - title: "Ecosystem" - - - file: ray-core/walkthrough - title: "Ray Core" - sections: - - file: ray-core/key-concepts - title: "Key Concepts" - - file: ray-core/user-guide - title: "User Guides" - - file: ray-core/examples/overview - title: "Examples" - sections: - - file: ray-core/examples/gentle_walkthrough - - file: ray-core/examples/monte_carlo_pi - - file: ray-core/examples/plot_example-lm - - file: ray-core/examples/plot_hyperparameter - - file: ray-core/examples/plot_parameter_server - - file: ray-core/examples/plot_pong_example - - file: ray-core/examples/highly_parallel - - file: ray-core/examples/batch_prediction - - file: ray-core/examples/batch_training - - file: ray-core/examples/automl_for_time_series - - file: ray-core/examples/web-crawler - - file: ray-core/examples/map_reduce - - file: ray-core/api/index - - - file: data/data - title: Ray Data - sections: - - file: data/overview - title: Overview - - file: data/key-concepts - - file: data/user-guide - - file: data/examples/index - - file: data/api/api - - file: data/data-internals - - - file: train/train - title: Ray Train - sections: - - file: train/overview - title: Overview - - file: train/getting-started-pytorch - title: PyTorch Guide - - file: train/getting-started-pytorch-lightning - title: PyTorch Lightning Guide - - file: train/getting-started-transformers - title: Hugging Face Transformers Guide - - file: train/more-frameworks - sections: - - file: train/huggingface-accelerate - title: Hugging Face Accelerate Guide - - file: train/deepspeed - title: DeepSpeed Guide - - file: train/distributed-tensorflow-keras - title: TensorFlow and Keras Guide - - file: train/distributed-xgboost-lightgbm - title: XGBoost and LightGBM Guide - - file: train/horovod - title: Horovod Guide - - file: train/user-guides - title: User Guides - - file: train/examples - title: "Examples" - - file: train/benchmarks - title: "Benchmarks" - - file: train/api/api - - - file: tune/index - title: Ray Tune - sections: - - file: tune/getting-started - title: "Getting Started" - - file: tune/key-concepts - title: "Key Concepts" - - file: tune/tutorials/overview - sections: - - file: tune/tutorials/tune-run - title: "Running Basic Experiments" - - file: tune/tutorials/tune-output - - file: tune/tutorials/tune-resources - title: "Setting Trial Resources" - - file: tune/tutorials/tune-search-spaces - title: "Using Search Spaces" - - file: tune/tutorials/tune-stopping - - file: tune/tutorials/tune-trial-checkpoints - - file: tune/tutorials/tune-storage - - file: tune/tutorials/tune-fault-tolerance - - file: tune/tutorials/tune-metrics - title: "Using Callbacks and Metrics" - - file: tune/tutorials/tune_get_data_in_and_out - - file: tune/examples/tune_analyze_results - - file: tune/examples/pbt_guide - sections: - - file: tune/examples/pbt_visualization/pbt_visualization - title: "Visualizing and Understanding PBT" - - file: tune/tutorials/tune-distributed - title: "Deploying Tune in the Cloud" - - file: tune/tutorials/tune-lifecycle - title: "Tune Architecture" - - file: tune/tutorials/tune-scalability - title: "Scalability Benchmarks" - - file: tune/examples/index - sections: - - file: tune/examples/ml-frameworks - sections: - - file: tune/examples/tune-sklearn - title: "Scikit-Learn Example" - - file: tune/examples/tune_mnist_keras - title: "Keras Example" - - file: tune/examples/tune-pytorch-cifar - title: "PyTorch Example" - - file: tune/examples/tune-pytorch-lightning - title: "PyTorch Lightning Example" - - file: tune/examples/tune-serve-integration-mnist - title: "Ray Serve Example" - - file: tune/examples/pbt_ppo_example - title: "Ray RLlib Example" - - file: tune/examples/tune-xgboost - title: "XGBoost Example" - - file: tune/examples/lightgbm_example - title: "LightGBM Example" - - file: tune/examples/horovod_simple - title: "Horovod Example" - - file: tune/examples/pbt_transformers - title: "Hugging Face Transformers Example" - - file: tune/examples/experiment-tracking - sections: - - file: tune/examples/tune-wandb - title: "Weights & Biases Example" - - file: tune/examples/tune-mlflow - title: "MLflow Example" - - file: tune/examples/tune-aim - title: "Aim Example" - - file: tune/examples/tune-comet - title: "Comet Example" - - file: tune/examples/hpo-frameworks - sections: - - file: tune/examples/ax_example - title: "Ax Example" - - file: tune/examples/dragonfly_example - title: "Dragonfly Example" - - file: tune/examples/hyperopt_example - title: "HyperOpt Example" - - file: tune/examples/bayesopt_example - title: "Bayesopt Example" - - file: tune/examples/flaml_example - title: "FLAML Example" - - file: tune/examples/bohb_example - title: "BOHB Example" - - file: tune/examples/nevergrad_example - title: "Nevergrad Example" - - file: tune/examples/optuna_example - title: "Optuna Example" - - file: tune/examples/sigopt_example - title: "SigOpt Example" - - file: tune/examples/other-examples - title: "Other Examples" - - file: tune/examples/exercises - title: "Exercises" - - file: tune/faq - - file: tune/api/api.rst - - - file: serve/index - title: Ray Serve - sections: - - file: serve/getting_started - - file: serve/key-concepts - - file: serve/develop-and-deploy - - file: serve/model_composition - - file: serve/multi-app - - file: serve/model-multiplexing - - file: serve/configure-serve-deployment - - file: serve/http-guide - - file: serve/production-guide/index - title: Production Guide - sections: - - file: serve/production-guide/config - - file: serve/production-guide/kubernetes - - file: serve/production-guide/docker - - file: serve/production-guide/fault-tolerance - - file: serve/production-guide/handling-dependencies - - file: serve/production-guide/best-practices - - file: serve/monitoring - - file: serve/resource-allocation - - file: serve/autoscaling-guide - - file: serve/advanced-guides/index - sections: - - file: serve/advanced-guides/app-builder-guide - - file: serve/advanced-guides/advanced-autoscaling - - file: serve/advanced-guides/performance - - file: serve/advanced-guides/dyn-req-batch - - file: serve/advanced-guides/inplace-updates - - file: serve/advanced-guides/dev-workflow - - file: serve/advanced-guides/grpc-guide - - file: serve/advanced-guides/deployment-graphs - - file: serve/advanced-guides/managing-java-deployments - - file: serve/advanced-guides/deploy-vm - - file: serve/architecture - - file: serve/tutorials/index - - file: serve/api/index - - - file: rllib/index - title: Ray RLlib - sections: - - file: rllib/rllib-training - - file: rllib/key-concepts - - file: rllib/rllib-env - - file: rllib/rllib-algorithms - - file: rllib/user-guides - sections: - - file: rllib/rllib-advanced-api - - file: rllib/rllib-models - - file: rllib/rllib-saving-and-loading-algos-and-policies - - file: rllib/rllib-concepts - - file: rllib/rllib-sample-collection - - file: rllib/rllib-replay-buffers - - file: rllib/rllib-offline - - file: rllib/rllib-catalogs - - file: rllib/rllib-connector - - file: rllib/rllib-rlmodule - - file: rllib/rllib-learner - - file: rllib/rllib-torch2x - - file: rllib/rllib-fault-tolerance - - file: rllib/rllib-dev - - file: rllib/rllib-cli - - file: rllib/rllib-examples - - file: rllib/package_ref/index - - - file: ray-more-libs/index - title: More Libraries - sections: - - file: ray-more-libs/joblib - - file: ray-more-libs/multiprocessing - - file: ray-more-libs/ray-collective - - file: ray-more-libs/dask-on-ray - - file: ray-more-libs/raydp - - file: ray-more-libs/mars-on-ray - - file: ray-more-libs/modin/index - - file: workflows/index - title: Ray Workflows (Alpha) - sections: - - file: workflows/key-concepts - - file: workflows/basics - - file: workflows/management - - file: workflows/metadata - - file: workflows/events - - file: workflows/comparison - - file: workflows/advanced - - file: workflows/api/api - - - file: cluster/getting-started - title: "Ray Clusters" - sections: - - file: cluster/key-concepts - title: Key Concepts - - file: cluster/kubernetes/index - title: Deploying on Kubernetes - sections: - - file: cluster/kubernetes/getting-started - sections: - - file: cluster/kubernetes/getting-started/raycluster-quick-start.md - - file: cluster/kubernetes/getting-started/rayjob-quick-start.md - - file: cluster/kubernetes/getting-started/rayservice-quick-start.md - - file: cluster/kubernetes/user-guides - sections: - - file: cluster/kubernetes/user-guides/rayservice.md - title: Deploy Ray Serve Apps - - file: cluster/kubernetes/user-guides/rayservice-high-availability.md - - file: cluster/kubernetes/user-guides/observability.md - - file: cluster/kubernetes/user-guides/upgrade-guide.md - - file: cluster/kubernetes/user-guides/k8s-cluster-setup.md - sections: - - file: cluster/kubernetes/user-guides/aws-eks-gpu-cluster.md - - file: cluster/kubernetes/user-guides/gcp-gke-gpu-cluster.md - - file: cluster/kubernetes/user-guides/storage.md - - file: cluster/kubernetes/user-guides/config.md - - file: cluster/kubernetes/user-guides/configuring-autoscaling.md - - file: cluster/kubernetes/user-guides/kuberay-gcs-ft.md - - file: cluster/kubernetes/user-guides/gke-gcs-bucket.md - - file: cluster/kubernetes/user-guides/logging.md - - file: cluster/kubernetes/user-guides/gpu.md - - file: cluster/kubernetes/user-guides/rayserve-dev-doc.md - - file: cluster/kubernetes/user-guides/pod-command.md - - file: cluster/kubernetes/user-guides/pod-security.md - - file: cluster/kubernetes/user-guides/helm-chart-rbac.md - - file: cluster/kubernetes/user-guides/tls.md - - file: cluster/kubernetes/user-guides/k8s-autoscaler.md - - file: cluster/kubernetes/user-guides/static-ray-cluster-without-kuberay.md - - file: cluster/kubernetes/examples - sections: - - file: cluster/kubernetes/examples/ml-example.md - - file: cluster/kubernetes/examples/gpu-training-example.md - - file: cluster/kubernetes/examples/stable-diffusion-rayservice.md - - file: cluster/kubernetes/examples/mobilenet-rayservice.md - - file: cluster/kubernetes/examples/text-summarizer-rayservice.md - - file: cluster/kubernetes/examples/rayjob-batch-inference-example.md - - file: cluster/kubernetes/k8s-ecosystem - sections: - - file: cluster/kubernetes/k8s-ecosystem/ingress.md - - file: cluster/kubernetes/k8s-ecosystem/prometheus-grafana.md - - file: cluster/kubernetes/k8s-ecosystem/pyspy.md - - file: cluster/kubernetes/k8s-ecosystem/volcano.md - - file: cluster/kubernetes/k8s-ecosystem/kubeflow.md - - file: cluster/kubernetes/benchmarks - sections: - - file: cluster/kubernetes/benchmarks/memory-scalability-benchmark.md - - file: cluster/kubernetes/troubleshooting - sections: - - file: cluster/kubernetes/troubleshooting/troubleshooting.md - - file: cluster/kubernetes/troubleshooting/rayservice-troubleshooting.md - - file: cluster/kubernetes/references - - file: cluster/vms/index - title: Deploying on VMs - sections: - - file: cluster/vms/getting-started - - file: cluster/vms/user-guides/index - title: User Guides - sections: - - file: cluster/vms/user-guides/launching-clusters/index - - file: cluster/vms/user-guides/large-cluster-best-practices - - file: cluster/vms/user-guides/configuring-autoscaling - - file: cluster/vms/user-guides/logging - - file: cluster/vms/user-guides/community/index - title: Community-supported Cluster Managers - sections: - - file: cluster/vms/user-guides/community/yarn - - file: cluster/vms/user-guides/community/slurm - - file: cluster/vms/user-guides/community/lsf - - file: cluster/vms/examples/index - title: Examples - sections: - - file: cluster/vms/examples/ml-example - - file: cluster/vms/references/index - - file: cluster/metrics - - file: cluster/configure-manage-dashboard - - file: cluster/running-applications/index - title: Applications Guide - - file: cluster/faq - - file: cluster/package-overview - - file: cluster/usage-stats - - - file: ray-observability/index - title: "Monitoring and Debugging" - sections: - - file: ray-observability/getting-started - - file: ray-observability/key-concepts - - file: ray-observability/user-guides/index - title: User Guides - sections: - - file: ray-observability/user-guides/debug-apps/index - title: Debugging Applications - sections: - - file: ray-observability/user-guides/debug-apps/general-debugging - - file: ray-observability/user-guides/debug-apps/debug-memory - - file: ray-observability/user-guides/debug-apps/debug-hangs - - file: ray-observability/user-guides/debug-apps/debug-failures - - file: ray-observability/user-guides/debug-apps/optimize-performance - - file: ray-observability/user-guides/debug-apps/ray-debugging - - file: ray-observability/user-guides/cli-sdk - - file: ray-observability/user-guides/configure-logging - - file: ray-observability/user-guides/profiling - - file: ray-observability/user-guides/add-app-metrics - - file: ray-observability/user-guides/ray-tracing - - file: ray-observability/reference/index - title: Reference - sections: - - file: ray-observability/reference/api - - file: ray-observability/reference/cli - - file: ray-observability/reference/system-metrics - - - file: ray-contribute/index - title: Developer Guides - - - file: ray-references/glossary - title: "Glossary" - - - file: ray-security/index - title: "Security" diff --git a/doc/source/conf.py b/doc/source/conf.py index 027f5398a18a..cd2d8a05b8fe 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,18 +1,31 @@ +from typing import List, Dict, Union, Any +import copy +import yaml from datetime import datetime from pathlib import Path from importlib import import_module import os import sys from jinja2.filters import FILTERS +import sphinx +from sphinx.ext import autodoc +from sphinx.util.nodes import make_refnode +from docutils import nodes +import pathlib +import bs4 +import logging + +logger = logging.getLogger(__name__) + sys.path.insert(0, os.path.abspath(".")) -from custom_directives import ( +from custom_directives import ( # noqa DownloadAndPreprocessEcosystemDocs, update_context, LinkcheckSummarizer, - build_gallery, ) + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -39,16 +52,13 @@ "sphinx-jsonschema", "sphinxemoji.sphinxemoji", "sphinx_copybutton", - "versionwarning.extension", "sphinx_sitemap", "myst_nb", "sphinx.ext.doctest", "sphinx.ext.coverage", "sphinx.ext.autosummary", - "sphinx_external_toc", "sphinxcontrib.autodoc_pydantic", "sphinxcontrib.redoc", - "sphinx_tabs.tabs", "sphinx_remove_toctrees", "sphinx_design", "sphinx.ext.intersphinx", @@ -97,13 +107,25 @@ "replacements", ] +myst_heading_anchors = 3 + # Cache notebook outputs in _build/.jupyter_cache -# To prevent notebook execution, set this to "off". To force re-execution, set this to "force". -# To cache previous runs, set this to "cache". -jupyter_execute_notebooks = os.getenv("RUN_NOTEBOOKS", "off") +# To prevent notebook execution, set this to "off". To force re-execution, set this to +# "force". To cache previous runs, set this to "cache". +nb_execution_mode = os.getenv("RUN_NOTEBOOKS", "off") -external_toc_exclude_missing = False -external_toc_path = "_toc.yml" +# Add a render priority for doctest +nb_mime_priority_overrides = [ + ("html", "application/vnd.jupyter.widget-view+json", 10), + ("html", "application/javascript", 20), + ("html", "text/html", 30), + ("html", "image/svg+xml", 40), + ("html", "image/png", 50), + ("html", "image/jpeg", 60), + ("html", "text/markdown", 70), + ("html", "text/latex", 80), + ("html", "text/plain", 90), +] html_extra_path = ["robots.txt"] @@ -124,7 +146,7 @@ # Special mocking of packaging.version.Version is required when using sphinx; # we can't just add this to autodoc_mock_imports, as packaging is imported by # sphinx even before it can be mocked. Instead, we patch it here. -import packaging.version as packaging_version +import packaging.version as packaging_version # noqa Version = packaging_version.Version @@ -139,35 +161,9 @@ def __init__(self, version: str): packaging_version.Version = MockVersion -# This is used to suppress warnings about explicit "toctree" directives. -suppress_warnings = ["etoc.toctree"] - -versionwarning_admonition_type = "note" -versionwarning_banner_title = "Join the Ray Discuss Forums!" - -FORUM_LINK = "https://discuss.ray.io" -versionwarning_messages = { - # Re-enable this after Ray Summit. - # "latest": ( - # "This document is for the latest pip release. " - # 'Visit the master branch documentation here.' - # ), - # "master": ( - # "Got questions? Join " - # f'the Ray Community forum ' - # "for Q&A on all things Ray, as well as to share and learn use cases " - # "and best practices with the Ray community." - # ), -} - -versionwarning_body_selector = "#main-content" - # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] -# The encoding of source files. -# source_encoding = 'utf-8-sig' - # The master toctree document. master_doc = "index" @@ -176,16 +172,16 @@ def __init__(self, version: str): copyright = str(datetime.now().year) + ", The Ray Team" author = "The Ray Team" -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the +# The version info for the project you're documenting acts as replacement for +# |version| and |release|, and is also used in various other places throughout the # built documents. Retrieve the version using `find_version` rather than importing # directly (from ray import __version__) because initializing ray will prevent # mocking of certain external dependencies. -from setup import find_version +from setup import find_version # noqa release = find_version("ray", "_version.py") -language = None +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -258,26 +254,62 @@ def __init__(self, version: str): # -- Options for HTML output ---------------------------------------------- + +def render_svg_logo(path): + with open(pathlib.Path(__file__).parent / path, "r") as f: + content = f.read() + + return content + + # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "sphinx_book_theme" +html_theme = "pydata_sphinx_theme" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - "repository_url": "https://github.com/ray-project/ray", - "use_repository_button": True, - "use_issues_button": True, "use_edit_page_button": True, - "path_to_docs": "doc/source", - "home_page_in_toc": True, - "show_navbar_depth": 1, - "announcement": "
", + "announcement": None, + "logo": { + "svg": render_svg_logo("_static/img/ray_logo.svg"), + }, + "navbar_start": ["navbar-ray-logo"], + "navbar_end": [ + "navbar-icon-links", + "navbar-anyscale", + ], + "navbar_center": ["navbar-links"], + "navbar_align": "left", + "navbar_persistent": [ + "theme-switcher", + ], + "secondary_sidebar_items": [ + "page-toc", + "edit-this-page", + ], + "content_footer_items": [ + "csat", + ], + "navigation_depth": 8, + "analytics": {"google_analytics_id": "UA-110413294-1"}, } -# Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = [] +html_context = { + "github_user": "ray-project", + "github_repo": "ray", + "github_version": "master", + "doc_path": "doc/source/", +} + +html_sidebars = { + "**": [ + "search-button-field", + "main-sidebar", + ], + "ray-overview/examples": ["examples-sidebar"], +} # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -285,9 +317,6 @@ def __init__(self, version: str): autodoc_typehints_format = "short" -# A shorter title for the navigation bar. Default is the same as html_title. -# html_short_title = None - # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. @@ -354,21 +383,176 @@ def filter_out_undoc_class_members(member_name, class_name, module_name): FILTERS["filter_out_undoc_class_members"] = filter_out_undoc_class_members -# Add a render priority for doctest -nb_render_priority = { - "doctest": (), - "html": ( - "application/vnd.jupyter.widget-view+json", - "application/javascript", - "text/html", - "image/svg+xml", - "image/png", - "image/jpeg", - "text/markdown", - "text/latex", - "text/plain", - ), -} + +def parse_navbar_config(app: sphinx.application.Sphinx, config: sphinx.config.Config): + """Parse the navbar config file into a set of links to show in the navbar. + + Parameters + ---------- + app : sphinx.application.Sphinx + Application instance passed when the `config-inited` event is emitted + config : sphinx.config.Config + Initialized configuration to be modified + """ + if "navbar_content_path" in config: + filename = app.config["navbar_content_path"] + else: + filename = "" + + if filename: + with open(pathlib.Path(__file__).parent / filename, "r") as f: + config.navbar_content = yaml.safe_load(f) + else: + config.navbar_content = None + + +NavEntry = Dict[str, Union[str, List["NavEntry"]]] + + +def setup_context(app, pagename, templatename, context, doctree): + def render_header_nav_links() -> bs4.BeautifulSoup: + """Render external header links into the top nav bar. + The structure rendered here is defined in an external yaml file. + + Returns + ------- + str + Raw HTML to be rendered in the top nav bar + """ + if not hasattr(app.config, "navbar_content"): + raise ValueError( + "A template is attempting to call render_header_nav_links(); a " + "navbar configuration must be specified." + ) + + node = nodes.container(classes=["navbar-content"]) + node.append(render_header_nodes(app.config.navbar_content)) + header_soup = bs4.BeautifulSoup( + app.builder.render_partial(node)["fragment"], "html.parser" + ) + return add_nav_chevrons(header_soup) + + def render_header_nodes( + obj: List[NavEntry], is_top_level: bool = True + ) -> nodes.Node: + """Generate a set of header nav links with docutils nodes. + + Parameters + ---------- + is_top_level : bool + True if the call to this function is rendering the top level nodes, + False otherwise (non-top level nodes are displayed as submenus of the top + level nodes) + obj : List[NavEntry] + List of yaml config entries to render as docutils nodes + + Returns + ------- + nodes.Node + Bullet list which will be turned into header nav HTML by the sphinx builder + """ + bullet_list = nodes.bullet_list( + bullet="-", + classes=["navbar-toplevel" if is_top_level else "navbar-sublevel"], + ) + + for item in obj: + + if "file" in item: + ref_node = make_refnode( + app.builder, + context["current_page_name"], + item["file"], + None, + nodes.inline(classes=["navbar-link-title"], text=item.get("title")), + item.get("title"), + ) + elif "link" in item: + ref_node = nodes.reference("", "", internal=False) + ref_node["refuri"] = item.get("link") + ref_node["reftitle"] = item.get("title") + ref_node.append( + nodes.inline(classes=["navbar-link-title"], text=item.get("title")) + ) + + if "caption" in item: + caption = nodes.Text(item.get("caption")) + ref_node.append(caption) + + paragraph = nodes.paragraph() + paragraph.append(ref_node) + + container = nodes.container(classes=["ref-container"]) + container.append(paragraph) + + list_item = nodes.list_item( + classes=["active-link"] if item.get("file") == pagename else [] + ) + list_item.append(container) + + if "sections" in item: + wrapper = nodes.container(classes=["navbar-dropdown"]) + wrapper.append( + render_header_nodes(item["sections"], is_top_level=False) + ) + list_item.append(wrapper) + + bullet_list.append(list_item) + + return bullet_list + + context["render_header_nav_links"] = render_header_nav_links + + +def add_nav_chevrons(input_soup: bs4.BeautifulSoup) -> bs4.BeautifulSoup: + """Add dropdown chevron icons to the header nav bar. + + Parameters + ---------- + input_soup : bs4.BeautifulSoup + Soup containing rendered HTML which will be inserted into the header nav bar + + Returns + ------- + bs4.BeautifulSoup + A new BeautifulSoup instance containing chevrons on the list items that + are meant to be dropdowns. + """ + soup = copy.copy(input_soup) + + for li in soup.find_all("li", recursive=True): + divs = li.find_all("div", {"class": "navbar-dropdown"}, recursive=False) + if divs: + ref = li.find("div", {"class": "ref-container"}) + ref.append(soup.new_tag("i", attrs={"class": "fa-solid fa-chevron-down"})) + + return soup + + +def add_custom_assets( + app: sphinx.application.Sphinx, + pagename: str, + templatename: str, + context: Dict[str, Any], + doctree: nodes.Node, +): + """Add custom per-page 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 == "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") + app.add_js_file("js/examples.js") + elif pagename == "ray-overview/ray-libraries": + app.add_css_file("css/ray-libraries.css") def setup(app): @@ -378,31 +562,25 @@ def setup(app): import doctest doctest.register_optionflag("MOCK") - app.connect("html-page-context", update_context) - # Custom CSS - app.add_css_file("css/custom.css", priority=800) - app.add_css_file( - "https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" - ) - # https://github.com/ines/termynal - app.add_css_file("css/termynal.css") - - # Custom JS - app.add_js_file( - "https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js", - defer="defer", - ) - app.add_js_file("js/docsearch.js", defer="defer") - app.add_js_file("js/csat.js", defer="defer") + app.add_config_value("navbar_content_path", "navbar.yml", "env") + app.connect("config-inited", parse_navbar_config) + app.connect("html-page-context", setup_context) + app.connect("html-page-context", add_custom_assets) # https://github.com/ines/termynal app.add_js_file("js/termynal.js", defer="defer") + app.add_css_file("css/termynal.css") + app.add_js_file("js/custom.js", defer="defer") - app.add_js_file("js/assistant.js", defer="defer") + app.add_css_file("css/custom.css", priority=800) + + app.add_js_file("js/csat.js") + app.add_css_file("css/csat.css") - app.add_js_file("js/top-navigation.js", defer="defer") + app.add_js_file("js/assistant.js", defer="defer") + app.add_css_file("css/assistant.css") base_path = Path(__file__).parent github_docs = DownloadAndPreprocessEcosystemDocs(base_path) @@ -416,12 +594,6 @@ def setup(app): app.connect("builder-inited", linkcheck_summarizer.add_handler_to_linkcheck) app.connect("build-finished", linkcheck_summarizer.summarize) - # Create galleries on the fly - app.connect("builder-inited", build_gallery) - - # tag filtering system - app.add_js_file("js/tags.js") - redoc = [ { @@ -458,6 +630,7 @@ def setup(app): "numpy", "pandas", "pyarrow", + "pydantic", "pytorch_lightning", "scipy", "setproctitle", @@ -475,13 +648,15 @@ def setup(app): "watchfiles", "xgboost", "xgboost_ray", + "psutil", + "colorama", + "grpc", # Internal compiled modules "ray._raylet", "ray.core.generated", "ray.serve.generated", ] - for mock_target in autodoc_mock_imports: assert mock_target not in sys.modules, ( f"Problematic mock target ({mock_target}) found; " @@ -489,10 +664,10 @@ def setup(app): "been loaded into sys.modules when the sphinx build starts." ) -from sphinx.ext import autodoc - class MockedClassDocumenter(autodoc.ClassDocumenter): + """Remove note about base class when a class is derived from object.""" + def add_line(self, line: str, source: str, *lineno: int) -> None: if line == " Bases: :py:class:`object`": return @@ -501,6 +676,7 @@ def add_line(self, line: str, source: str, *lineno: int) -> None: autodoc.ClassDocumenter = MockedClassDocumenter + # Other sphinx docs can be linked to if the appropriate URL to the docs # is specified in the `intersphinx_mapping` - for example, types annotations # that are defined in dependencies can link to their respective documentation. @@ -520,6 +696,7 @@ def add_line(self, line: str, source: str, *lineno: int) -> None: "numpy": ("https://numpy.org/doc/stable/", None), "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None), "pyarrow": ("https://arrow.apache.org/docs", None), + "pydantic": ("https://docs.pydantic.dev/latest/", None), "pymongoarrow": ("https://mongo-arrow.readthedocs.io/en/latest/", None), "pyspark": ("https://spark.apache.org/docs/latest/api/python/", None), "python": ("https://docs.python.org/3", None),