diff --git a/doc/README.md b/doc/README.md index f4c20c3f9064..92c23f50f9f0 100644 --- a/doc/README.md +++ b/doc/README.md @@ -84,7 +84,7 @@ The benefits of working with notebooks for examples are that you don't separate ## Adding Markdown docs from external (ecosystem) repositories -In order to avoid a situation where duplicate documentation files live in both the docs folder +In order to avoid a situation where duplicate documentation files live in both the `doc/` folder in this repository and in external repositories of ecosystem libraries (eg. xgboost-ray), you can specify Markdown files that will be downloaded from other GitHub repositories during the build process. diff --git a/doc/source/ray-contribute/docs.ipynb b/doc/source/ray-contribute/docs.ipynb index bbeec38410bb..4df5eaabc47c 100644 --- a/doc/source/ray-contribute/docs.ipynb +++ b/doc/source/ray-contribute/docs.ipynb @@ -507,9 +507,9 @@ "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", + "2. **Check your environment.** Use `pip list` to check the installed dependencies. Compare them to `doc/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 doc/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 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", + "4. **Enable breakpoints in Sphinx**. Add -P to the `SPHINXOPTS` in `doc/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",