[Docs] Fix documentation building instructions (ray-project#25942)

It is often a bit challenging to get the full documentation to build (there are external packages that can make this challenging). This changes the instructions to treat warnings as warnings and not errors, which should improve the workflow.

`make develop` is the same as `make html` except it doesn't treat warnings as errors.

doc/README.md

@@ -16,9 +16,12 @@ pip install -r requirements-doc.txt
 To compile the documentation and open it locally, run the following command from this directory.
 
 ```bash
-make html && open _build/html/index.html
+make develop && open _build/html/index.html
 ```
 
+> **_NOTE:_**  The above command is for development. To reproduce build failures from the
+> CI, you should use `make html` which is the same as `make develop` but treats warnings as errors.
+
 ## Building just one sub-project
 
 Often your changes in documentation just concern one sub-project, such as Tune or Train.
@@ -67,12 +70,12 @@ make doctest
 You can now add [executable notebooks](https://myst-nb.readthedocs.io/en/latest/use/markdown.html) to this project,
 which will get built into the documentation.
 An [example can be found here](./source/serve/tutorials/rllib.md).
-By default, building the docs with `make html` will not run those notebooks.
+By default, building the docs with `make develop` will not run those notebooks.
 If you set the `RUN_NOTEBOOKS` environment variable to `"cache"`, each notebook cell will be run when you build the
 documentation, and outputs will be cached into `_build/.jupyter_cache`.
 
 ```bash
-RUN_NOTEBOOKS="cache" make html
+RUN_NOTEBOOKS="cache" make develop
 ```
 
 To force re-running the notebooks, use `RUN_NOTEBOOKS="force"`.

doc/source/ray-contribute/docs.ipynb

@@ -45,7 +45,7 @@
     "Building the documentation is done by running the following command:\n",
     "\n",
     "```shell\n",
-    "make html\n",
+    "make develop\n",
     "```\n",
     "\n",
     "which will build the documentation into the `_build` directory.\n",
@@ -57,6 +57,9 @@
     "with `../scripts/format.sh` from the `doc` folder,\n",
     "to make sure your changes are formatted correctly.\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",
     "## Building Docs for Apple Silicon (M1)\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",