Skip to content

Commit

Permalink
[Doc] Add documentation build system troubleshooting guidelines (ray-…
Browse files Browse the repository at this point in the history
…project#42818)

* [Doc] Add documentation build system troubleshooting guidelines

Signed-off-by: pdmurray <[email protected]>

* Update doc/source/ray-contribute/docs.ipynb

Co-authored-by: angelinalg <[email protected]>
Signed-off-by: Peyton Murray <[email protected]>

* Update doc/source/ray-contribute/docs.ipynb

Co-authored-by: angelinalg <[email protected]>
Signed-off-by: Peyton Murray <[email protected]>

* Update doc/source/ray-contribute/docs.ipynb

Co-authored-by: angelinalg <[email protected]>
Signed-off-by: Peyton Murray <[email protected]>

* Update doc/source/ray-contribute/docs.ipynb

Co-authored-by: angelinalg <[email protected]>
Signed-off-by: Peyton Murray <[email protected]>

* Update doc/source/ray-contribute/docs.ipynb

Co-authored-by: angelinalg <[email protected]>
Signed-off-by: Peyton Murray <[email protected]>

* Update doc/source/ray-contribute/docs.ipynb

Co-authored-by: angelinalg <[email protected]>
Signed-off-by: Peyton Murray <[email protected]>

* Update doc/source/ray-contribute/docs.ipynb

Co-authored-by: angelinalg <[email protected]>
Signed-off-by: Peyton Murray <[email protected]>

* Finish addressing comments

Signed-off-by: pdmurray <[email protected]>

* Add instructions for creating and activating a conda environment

Signed-off-by: pdmurray <[email protected]>

---------

Signed-off-by: pdmurray <[email protected]>
Signed-off-by: Peyton Murray <[email protected]>
Co-authored-by: angelinalg <[email protected]>
peytondmurray and angelinalg authored Feb 1, 2024
1 parent 55a4ee4 commit d7b27b8
Showing 1 changed file with 34 additions and 35 deletions.
69 changes: 34 additions & 35 deletions doc/source/ray-contribute/docs.ipynb
Original file line number Diff line number Diff line change
@@ -33,7 +33,7 @@
"## Building the Ray documentation\n",
"\n",
"If you want to contribute to the Ray documentation, you need a way to build it.\n",
"You don't have to build Ray itself, which is a bit more involved.\n",
"Don't install Ray in the environment you plan to use to build documentation. The requirements for the docs build system are generally not compatible with those you need to run Ray itself.\n",
"\n",
"Follow the instructions in [Building Ray from Source](https://docs.ray.io/en/master/ray-contribute/development.html#building-ray-from-source) up to and including the following:\n",
"1. [Fork the Ray repository](https://docs.ray.io/en/master/ray-contribute/development.html#fork-the-ray-repository)\n",
@@ -46,35 +46,24 @@
"cd ray/doc\n",
"```\n",
"\n",
"## Building Docs for Apple Silicon (M1)\n",
"\n",
"Note: If you are not using Apple Silicon (M1), skip to the [next section](#install-dependencies).\n",
"\n",
"If you are using an Apple Silicon (M1) some of the dependencies required for building the docs don't have binary packages available by default (not available in PyPI). \n",
"\n",
"The simplest way to install those dependencies is with `conda` (https://docs.conda.io/en/latest/miniconda.html) first, that way `pip` won't try to install them by building them from scratch.\n",
"\n",
"To do that, make sure you create and/or activate the conda environment, and then install the dependencies with:\n",
"\n",
"## Install Dependencies\n",
"\n",
"If you haven't done so already, create a Python environment, preferably using the latest version of Python. For example, if you're using `conda`:\n",
"```shell\n",
"conda install -c conda-forge xgboost lightgbm\n",
"conda create -n docs python=3.12\n",
"```\n",
"\n",
"## Install Dependencies\n",
"\n",
"Activate the Python environment you are using (e.g., venv, conda, etc.). Install the documentation dependencies, with the following command:\n",
"\n",
"Next, activate the Python environment you are using (e.g., venv, conda, etc.). With `conda` this would be:\n",
"```shell\n",
"pip install -r requirements-doc.txt\n",
"conda activate docs\n",
"```\n",
"\n",
"Install the dependencies for our linters to ensure your changes comply with our style guide.\n",
"Install the documentation dependencies with the following command:\n",
"\n",
"```shell\n",
"pip install -r ../python/requirements/lint-requirements.txt\n",
"pip install -r requirements-doc.txt\n",
"```\n",
"\n",
"Don't use `-U` in this step. You don't want to upgrade dependencies because `requirements-doc.txt` pins exact versions you need to build the docs.\n",
"\n",
"Build the documentation by running the following command:\n",
"\n",
"```shell\n",
@@ -90,18 +79,12 @@
"with `../scripts/format.sh` from the `doc` folder,\n",
"to make sure your changes are formatted correctly.\n",
"\n",
"If your local build does not seem to be rendering your latest local changes, try `make clean && sphinx-build -b html -d _build/doctrees source _build/html`.\n",
"\n",
"For reproducing CI build failures locally, you might want to use `make html`, which\n",
"is the same as `make develop` but treats warnings as errors.\n",
"\n",
"## The basics of our build system\n",
"\n",
"The Ray documentation is built using the [`sphinx`](https://www.sphinx-doc.org/) build system.\n",
"We're using the [Sphinx Book Theme](https://github.com/executablebooks/sphinx-book-theme) from the\n",
"[executable books project](https://github.com/executablebooks).\n",
"We're using the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/) for the documentation.\n",
"\n",
"That means that you can write Ray documentation in either Sphinx's native \n",
"We use [`myst-parser`](https://myst-parser.readthedocs.io/en/latest/) to allow you to write Ray documentation in either Sphinx's native \n",
"[reStructuredText (rST)](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) or in\n",
"[Markedly Structured Text (MyST)](https://myst-parser.readthedocs.io/en/latest/).\n",
"The two formats can be converted to each other, so the choice is up to you.\n",
@@ -517,23 +500,39 @@
"\n",
"If you want to use the word anyway, modify the appropriate field in the [WordList configuration](https://github.com/ray-project/ray/blob/81c169bde2414fe4237f3d2f05fc76fccfd52dee/.vale/styles/Google/WordList.yml#L41).\n",
"\n",
"## Troubleshooting\n",
"\n",
"If you run into a problem building the docs, following these steps can help isolate or eliminate most issues:\n",
"\n",
"1. **Clean out build artifacts.** Use `git clean -fdx ./` to clean out docs build artifacts in the working directory. This command does a more complete job than `make clean`. Sphinx uses caching to avoid doing work, and this sometimes causes problems. This is particularly true if you build the docs, then `git pull origin master` to pull in recent changes, and then try to build docs again. Note that this will delete any newly added files that haven't been committed yet, so use with caution.\n",
"2. **Check your environment.** Use `pip list` to check the installed dependencies. Compare them to `docs/requirements-doc.txt`. The documentation build system doesn't have the same dependency requirements as Ray. You don't need to run ML models or execute code on distributed systems in order to build the docs. In fact, it's best to use a completely separate docs build environment from the environment you use to run Ray to avoid dependency conflicts. When installing requirements, do `pip install -r docs/requirements-doc.txt`. Don't use `-U` because you don't want to upgrade any dependencies during the installation.\n",
"3. **Ensure a modern version of Python.** The docs build system doesn't keep the same dependency and Python version requirements as Ray. Use a modern version of Python when building docs. Newer versions of Python can be substantially faster than preceding versions. Consult <https://endoflife.date/python> for the latest version support information.\n",
"4. **Enable breakpoints in Sphinx**. Add -P to the `SPHINXOPTS` in `docs/Makefile` to tell `sphinx` to stop when it encounters a breakpoint, and remove `-j auto` to disable parallel builds. Now you can put breakpoints in the modules you're trying to import, or in `sphinx` code itself, which can help isolate build stubborn build issues.\n",
"\n",
"## Where to go from here?\n",
"\n",
"There are many other ways to contribute to Ray other than documentation.\n",
"See {ref}`our contributor guide <getting-involved>` for more information."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": []
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.11.6"
}
},
"nbformat": 4,

0 comments on commit d7b27b8

Please sign in to comment.