2016-07-01 18:21:02 -07:00
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
2023-12-08 18:02:28 -08:00
# Allow linkcheck to run without treating warnings as errors; -W will
# fast-fail if enabled; it's better to gather the whole list of bad links at once.
2023-11-27 17:08:36 -08:00
SPHINXOPTS = -a -E -W -j auto
2024-07-30 13:25:35 -07:00
LOCALSPHINXOPTS = -W -j auto
2023-12-08 18:02:28 -08:00
LINKCHECKOPTS = -a -E -j auto
2016-07-01 18:21:02 -07:00
SPHINXBUILD = sphinx-build
2024-08-22 17:19:18 -07:00
SPHINXAUTOBUILD = sphinx-autobuild --port 0 --open-browser --ignore "*.log" --ignore "*data/examples*" --ignore "*train/examples*" --ignore "*serve/examples*"
2016-07-01 18:21:02 -07:00
PAPER =
BUILDDIR = _build
# User-friendly check for sphinx-build
i f e q ( $( shell which $ ( SPHINXBUILD ) >/dev /null 2>&1; echo $ $ ?) , 1 )
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http : //sphinx -doc .org /)
e n d i f
# Internal variables.
2023-12-08 18:02:28 -08:00
PAPEROPT_a4 = -D latex_paper_size = a4
PAPEROPT_letter = -D latex_paper_size = letter
ALLSPHINXOPTS = -d $( BUILDDIR) /doctrees $( PAPEROPT_$( PAPER) ) $( SPHINXOPTS) source
2024-07-30 13:25:35 -07:00
ALLLOCALSPHINXOPTS = -d $( BUILDDIR) /doctrees $( PAPEROPT_$( PAPER) ) $( LOCALSPHINXOPTS) source
2023-12-08 18:02:28 -08:00
ALLLINKCHECKOPTS = -d $( BUILDDIR) /doctrees $( PAPEROPT_$( PAPER) ) $( LINKCHECKOPTS) source
2016-07-01 18:21:02 -07:00
# the i18n builder cannot share the environment and doctrees with the others
2017-02-27 21:14:31 -08:00
I18NSPHINXOPTS = $( PAPEROPT_$( PAPER) ) $( SPHINXOPTS) source
2016-07-01 18:21:02 -07:00
2023-11-27 17:08:36 -08:00
.PHONY : help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext show
2016-07-01 18:21:02 -07:00
help :
@echo "Please use \`make <target>' where <target> is one of"
2023-12-13 23:43:01 -08:00
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " linkcheck_all to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
2016-07-01 18:21:02 -07:00
clean :
2022-02-19 10:19:07 +01:00
rm -rf $( BUILDDIR) /*
2024-06-28 02:28:08 +08:00
rm -rf ./source/__pycache__/
rm -rf ./source/_ext/__pycache__/
2023-05-11 10:48:05 +02:00
rm -rf ./source/*/api/doc/*
2025-02-26 16:38:32 -08:00
rm -rf ./source/ray-core/compiled-graph/doc/*
2023-05-11 10:48:05 +02:00
rm -rf ./source/ray-references/api/*/doc/*
rm -rf ./source/cluster/running_applications/doc/*
rm -rf ./source/cluster/running_applications/job-submission/doc/*
rm -rf ./source/ray-observability/api/state/doc*
rm -rf ./source/rllib/package_ref/doc*
2024-06-28 02:28:08 +08:00
rm -rf ./source/ray-more-libs/doc/*
rm -rf ./source/ray-observability/reference/doc/*
rm -f ./source/data/examples.rst
rm -f ./source/serve/examples.rst
rm -f ./source/train/examples.rst
2016-07-01 18:21:02 -07:00
html :
[Serve] Pydantic v2 Migration for Ray Serve (#61061)
This PR migrates Ray Serve from Pydantic v1 to v2, removing all
compatibility shims.
### Key API Changes
- `parse_obj()` → `model_validate()`
- `.dict()` → `.model_dump()`
- `.copy(update=...)` → `.model_copy(update=...)`
- `@validator` → `@field_validator` / `@model_validator`
- `class Config` → `model_config = ConfigDict(...)`
- Removed all `ray._common.pydantic_compat` imports
### Critical Quirks for Reviewers
#### 1. **`model_validate()` Bypasses `__init__`**
In Pydantic v2, `model_validate()` bypasses `__init__`, breaking
serialization logic in `AutoscalingPolicy` and `RequestRouterConfig`.
**Fix**: Added `@model_validator(mode="after")` to ensure
`serialize_policy()` and `_serialize_request_router_cls()` are called
#### 2. **`PrivateAttr` Breaks Equality**
Pydantic v2 includes `PrivateAttr` fields in `__eq__()` comparison.
Since `_serialized_policy_def` and `_serialized_request_router_cls`
contain cloudpickle'd bytecode (with timestamps), identical configs
compare as unequal, causing **infinite redeployment loops**.
**Fix**: Override `__eq__()` and `__hash__()` to only compare public
fields:
Related to https://github.com/ray-project/ray/issues/60680 and
https://github.com/ray-project/ray/issues/58876
The pydantic v2 migration for Ray Serve changed how config/schema models
are documented. The doc cache (built on master) contains autosummary
stubs generated with the default `class.rst` template, which creates
per-member stub files via nested `.. autosummary:: :toctree:`. Since
autosummary never overwrites existing stubs, these stale cached stubs
caused hundreds of "document isn't included in any toctree" and
"duplicate object description" warnings.
**Changes across 5 files:**
1. **`doc/Makefile`** -- Delete all cached serve API stubs
(`ray.serve.*.rst`) before the Sphinx build in both `html` and `local`
targets. This forces autosummary to regenerate them with the correct
templates. Needed while the remote doc cache predates the pydantic v2
migration.
2. **`doc/source/_templates/autosummary/autopydantic.rst`** -- Added
`:members:` to properly document pydantic v2 model fields inline.
Removed `:undoc-members:` (redundant with `:members:`).
3. **`doc/source/conf.py`**:
- Added `autodoc_pydantic_model_show_json = False` to prevent empty raw
directives from models with non-serializable fields.
- Extended `nitpick_ignore_regex` to suppress `py:obj` warnings
generated by autodoc_pydantic for pydantic v2 validators ("all fields",
`_validate_*`).
- Minor cleanup of `DuplicateObjectFilter` formatting.
4. **`doc/source/serve/api/index.md`** -- Split autosummary blocks to
use appropriate templates:
- Pydantic models (config classes, schemas) use `autopydantic.rst` --
documents fields inline, no per-member stubs.
- Enums and non-pydantic classes (`ProxyLocation`, `APIType`,
`ApplicationStatus`, etc.) use `class_without_autosummary.rst` -- no
nested autosummary stubs.
- Removed `schema.TaskProcessorAdapter` (no longer needed).
5. **`doc/source/serve/advanced-guides/advanced-autoscaling.md`** --
Updated 27 links from per-field `.rst` files (e.g.,
`AutoscalingConfig.target_ongoing_requests.rst`) to the main class page
(`AutoscalingConfig.rst`), since per-field stubs are no longer
generated.
---------
Signed-off-by: abrar <abrar@anyscale.com>
2026-03-05 21:35:27 -08:00
@# Remove cached serve API stubs so autosummary regenerates them with correct templates
find source/serve/api/doc/ -name "ray.serve.*.rst" -delete 2>/dev/null || true
2023-07-27 17:02:12 -07:00
$( SPHINXBUILD) -W --keep-going -b html $( ALLSPHINXOPTS) $( BUILDDIR) /html
2016-07-01 18:21:02 -07:00
@echo
@echo " Build finished. The HTML pages are in $( BUILDDIR) /html. "
2023-01-18 17:40:56 -08:00
@echo " View the documentation by opening a browser and going to $( BUILDDIR) /html/index.html. "
2024-02-20 14:27:03 -08:00
2024-02-02 10:05:00 -08:00
develop : html
2022-04-08 16:57:23 -07:00
2024-07-30 13:25:35 -07:00
RAY_DIR := $( shell pwd | rev | cut -d'/' -f2- | rev)
local :
2024-08-21 17:49:46 -07:00
python load_doc_cache.py --ray-dir= $( RAY_DIR)
[Serve] Pydantic v2 Migration for Ray Serve (#61061)
This PR migrates Ray Serve from Pydantic v1 to v2, removing all
compatibility shims.
### Key API Changes
- `parse_obj()` → `model_validate()`
- `.dict()` → `.model_dump()`
- `.copy(update=...)` → `.model_copy(update=...)`
- `@validator` → `@field_validator` / `@model_validator`
- `class Config` → `model_config = ConfigDict(...)`
- Removed all `ray._common.pydantic_compat` imports
### Critical Quirks for Reviewers
#### 1. **`model_validate()` Bypasses `__init__`**
In Pydantic v2, `model_validate()` bypasses `__init__`, breaking
serialization logic in `AutoscalingPolicy` and `RequestRouterConfig`.
**Fix**: Added `@model_validator(mode="after")` to ensure
`serialize_policy()` and `_serialize_request_router_cls()` are called
#### 2. **`PrivateAttr` Breaks Equality**
Pydantic v2 includes `PrivateAttr` fields in `__eq__()` comparison.
Since `_serialized_policy_def` and `_serialized_request_router_cls`
contain cloudpickle'd bytecode (with timestamps), identical configs
compare as unequal, causing **infinite redeployment loops**.
**Fix**: Override `__eq__()` and `__hash__()` to only compare public
fields:
Related to https://github.com/ray-project/ray/issues/60680 and
https://github.com/ray-project/ray/issues/58876
The pydantic v2 migration for Ray Serve changed how config/schema models
are documented. The doc cache (built on master) contains autosummary
stubs generated with the default `class.rst` template, which creates
per-member stub files via nested `.. autosummary:: :toctree:`. Since
autosummary never overwrites existing stubs, these stale cached stubs
caused hundreds of "document isn't included in any toctree" and
"duplicate object description" warnings.
**Changes across 5 files:**
1. **`doc/Makefile`** -- Delete all cached serve API stubs
(`ray.serve.*.rst`) before the Sphinx build in both `html` and `local`
targets. This forces autosummary to regenerate them with the correct
templates. Needed while the remote doc cache predates the pydantic v2
migration.
2. **`doc/source/_templates/autosummary/autopydantic.rst`** -- Added
`:members:` to properly document pydantic v2 model fields inline.
Removed `:undoc-members:` (redundant with `:members:`).
3. **`doc/source/conf.py`**:
- Added `autodoc_pydantic_model_show_json = False` to prevent empty raw
directives from models with non-serializable fields.
- Extended `nitpick_ignore_regex` to suppress `py:obj` warnings
generated by autodoc_pydantic for pydantic v2 validators ("all fields",
`_validate_*`).
- Minor cleanup of `DuplicateObjectFilter` formatting.
4. **`doc/source/serve/api/index.md`** -- Split autosummary blocks to
use appropriate templates:
- Pydantic models (config classes, schemas) use `autopydantic.rst` --
documents fields inline, no per-member stubs.
- Enums and non-pydantic classes (`ProxyLocation`, `APIType`,
`ApplicationStatus`, etc.) use `class_without_autosummary.rst` -- no
nested autosummary stubs.
- Removed `schema.TaskProcessorAdapter` (no longer needed).
5. **`doc/source/serve/advanced-guides/advanced-autoscaling.md`** --
Updated 27 links from per-field `.rst` files (e.g.,
`AutoscalingConfig.target_ongoing_requests.rst`) to the main class page
(`AutoscalingConfig.rst`), since per-field stubs are no longer
generated.
---------
Signed-off-by: abrar <abrar@anyscale.com>
2026-03-05 21:35:27 -08:00
@# Remove cached serve API stubs so autosummary regenerates them with correct templates
@# ( pydantic v2 migration changed templates; cached stubs use old template with nested
@# autosummary :toctree: that generates unwanted per-member stub files)
find source/serve/api/doc/ -name "ray.serve.*.rst" -delete 2>/dev/null || true
2024-08-21 17:49:46 -07:00
python update_cache_env.py --ray-dir= $( RAY_DIR)
2024-08-22 17:19:18 -07:00
$( SPHINXAUTOBUILD) -W --keep-going -b html $( ALLLOCALSPHINXOPTS) $( BUILDDIR) /html
2024-07-30 13:25:35 -07:00
2016-07-01 18:21:02 -07:00
dirhtml :
$( SPHINXBUILD) -b dirhtml $( ALLSPHINXOPTS) $( BUILDDIR) /dirhtml
@echo
@echo " Build finished. The HTML pages are in $( BUILDDIR) /dirhtml. "
singlehtml :
$( SPHINXBUILD) -b singlehtml $( ALLSPHINXOPTS) $( BUILDDIR) /singlehtml
@echo
@echo " Build finished. The HTML page is in $( BUILDDIR) /singlehtml. "
pickle :
$( SPHINXBUILD) -b pickle $( ALLSPHINXOPTS) $( BUILDDIR) /pickle
@echo
@echo "Build finished; now you can process the pickle files."
json :
$( SPHINXBUILD) -b json $( ALLSPHINXOPTS) $( BUILDDIR) /json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp :
$( SPHINXBUILD) -b htmlhelp $( ALLSPHINXOPTS) $( BUILDDIR) /htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
" .hhp project file in $( BUILDDIR) /htmlhelp. "
qthelp :
$( SPHINXBUILD) -b qthelp $( ALLSPHINXOPTS) $( BUILDDIR) /qthelp
@echo
@echo "Build finished; now you can run " qcollectiongenerator" with the" \
" .qhcp project file in $( BUILDDIR) /qthelp, like this: "
@echo " # qcollectiongenerator $( BUILDDIR) /qthelp/Ray.qhcp "
@echo "To view the help file:"
@echo " # assistant -collectionFile $( BUILDDIR) /qthelp/Ray.qhc "
applehelp :
$( SPHINXBUILD) -b applehelp $( ALLSPHINXOPTS) $( BUILDDIR) /applehelp
@echo
@echo " Build finished. The help book is in $( BUILDDIR) /applehelp. "
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
devhelp :
$( SPHINXBUILD) -b devhelp $( ALLSPHINXOPTS) $( BUILDDIR) /devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo " # mkdir -p $$ HOME/.local/share/devhelp/Ray "
@echo " # ln -s $( BUILDDIR) /devhelp $$ HOME/.local/share/devhelp/Ray "
@echo "# devhelp"
epub :
$( SPHINXBUILD) -b epub $( ALLSPHINXOPTS) $( BUILDDIR) /epub
@echo
@echo " Build finished. The epub file is in $( BUILDDIR) /epub. "
latex :
$( SPHINXBUILD) -b latex $( ALLSPHINXOPTS) $( BUILDDIR) /latex
@echo
@echo " Build finished; the LaTeX files are in $( BUILDDIR) /latex. "
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf :
$( SPHINXBUILD) -b latex $( ALLSPHINXOPTS) $( BUILDDIR) /latex
@echo "Running LaTeX files through pdflatex..."
$( MAKE) -C $( BUILDDIR) /latex all-pdf
@echo " pdflatex finished; the PDF files are in $( BUILDDIR) /latex. "
latexpdfja :
$( SPHINXBUILD) -b latex $( ALLSPHINXOPTS) $( BUILDDIR) /latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$( MAKE) -C $( BUILDDIR) /latex all-pdf-ja
@echo " pdflatex finished; the PDF files are in $( BUILDDIR) /latex. "
text :
$( SPHINXBUILD) -b text $( ALLSPHINXOPTS) $( BUILDDIR) /text
@echo
@echo " Build finished. The text files are in $( BUILDDIR) /text. "
man :
$( SPHINXBUILD) -b man $( ALLSPHINXOPTS) $( BUILDDIR) /man
@echo
@echo " Build finished. The manual pages are in $( BUILDDIR) /man. "
texinfo :
$( SPHINXBUILD) -b texinfo $( ALLSPHINXOPTS) $( BUILDDIR) /texinfo
@echo
@echo " Build finished. The Texinfo files are in $( BUILDDIR) /texinfo. "
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info :
$( SPHINXBUILD) -b texinfo $( ALLSPHINXOPTS) $( BUILDDIR) /texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $( BUILDDIR) /texinfo info
@echo " makeinfo finished; the Info files are in $( BUILDDIR) /texinfo. "
gettext :
$( SPHINXBUILD) -b gettext $( I18NSPHINXOPTS) $( BUILDDIR) /locale
@echo
@echo " Build finished. The message catalogs are in $( BUILDDIR) /locale. "
changes :
$( SPHINXBUILD) -b changes $( ALLSPHINXOPTS) $( BUILDDIR) /changes
@echo
@echo " The overview file is in $( BUILDDIR) /changes. "
linkcheck :
2023-12-08 18:02:28 -08:00
$( SPHINXBUILD) -b linkcheck $( ALLLINKCHECKOPTS) $( BUILDDIR) /linkcheck
2016-07-01 18:21:02 -07:00
@echo
@echo "Link check complete; look for any errors in the above output " \
" or in $( BUILDDIR) /linkcheck/output.txt. "
2023-12-13 23:43:01 -08:00
linkcheck_all :
LINKCHECK_ALL = 1 $( SPHINXBUILD) -b linkcheck $( ALLLINKCHECKOPTS) $( BUILDDIR) /linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
" or in $( BUILDDIR) /linkcheck/output.txt. "
2016-07-01 18:21:02 -07:00
doctest :
$( SPHINXBUILD) -b doctest $( ALLSPHINXOPTS) $( BUILDDIR) /doctest
@echo "Testing of doctests in the sources finished, look at the " \
" results in $( BUILDDIR) /doctest/output.txt. "
coverage :
$( SPHINXBUILD) -b coverage $( ALLSPHINXOPTS) $( BUILDDIR) /coverage
@echo "Testing of coverage in the sources finished, look at the " \
" results in $( BUILDDIR) /coverage/python.txt. "
xml :
$( SPHINXBUILD) -b xml $( ALLSPHINXOPTS) $( BUILDDIR) /xml
@echo
@echo " Build finished. The XML files are in $( BUILDDIR) /xml. "
pseudoxml :
$( SPHINXBUILD) -b pseudoxml $( ALLSPHINXOPTS) $( BUILDDIR) /pseudoxml
@echo
@echo " Build finished. The pseudo-XML files are in $( BUILDDIR) /pseudoxml. "
2023-11-27 17:08:36 -08:00
show :
python -m http.server -d _build/html/
