Repository for documentation of the Ray project, hosted at [docs.ray.io](https://docs.ray.io).
Sign in to like and favorite skills
Repository for documentation of the Ray project, hosted at docs.ray.io.
To build the documentation, make sure you have
raypip install -r requirements-doc.lock.txt
To compile the documentation and open it locally, run the following command from this directory.
make develop && open _build/html/index.html
Often your changes in documentation just concern one subproject, such as Tune or Train. To build just this one subproject, and ignore the rest (leading to build warnings due to broken references etc.), run the following command:
DOC_LIB=<project> sphinx-build -b html -d _build/doctrees source _build/html
where
<project>source/tunerllibtrainclusterservedataray-ray-observabilityTo add new announcements and other messaging to the top or bottom of a documentation page, check the
_includes.. include:: /_includes/<my-announcement>
This ensures consistent messaging across documentation pages.
To check if there are broken links, run the following (we are currently not running this in the CI since there are false positives).
make linkcheck
To run tests for examples shipping with docstrings in Python files, run the following command:
make doctest
You can now add executable notebooks to this project, which will get built into the documentation.
By default, building the docs with
make developRUN_NOTEBOOKS"cache"_build/.jupyter_cacheRUN_NOTEBOOKS="cache" make develop
To force re-running the notebooks, use
RUN_NOTEBOOKS="force"Using caching, this means the first time you build the documentation, it might take a while to run the notebooks. After that, notebook execution is only triggered when you change the notebook source file.
The benefits of working with notebooks for examples are that you don't separate the code from the documentation, but can still easily smoke-test the code.
In order to avoid a situation where duplicate documentation files live in both the
doc/In order to do that, simply edit the
EXTERNAL_MARKDOWN_FILESsource/custom_directives.pyWhile both GitHub Markdown and MyST are supersets of Common Markdown, there are differences in syntax. Furthermore, some contents such as Sphinx headers are not desirable to be displayed on GitHub. In order to deal with this, simple preprocessing is performed to allow for differences in rendering on GitHub and in docs. You can use two commands (
$UNCOMMENT$REMOVE$END_REMOVE$UNCOMMENTGitHub:
<!--$UNCOMMENTthis will be uncommented--> More text
In docs, this will become:
this will be uncommented More text
$REMOVE$END_REMOVEGitHub:
<!--$REMOVE-->This will be removed<!--$END_REMOVE--> More text
In docs, this will become:
More text
Please note that the parsing is extremely simple (regex replace) and will not support nesting.
If you want to run the preprocessing locally on a specific file (to eg. see how it will render after docs have been built), run
source/preprocess_github_markdown.py PATH_TO_MARKDOWN_FILE PATH_TO_PREPROCESSED_MARKDOWN_FILEEXTERNAL_MARKDOWN_FILESsource/custom_directives.py