From ff075d08150ec060f035b660789ebf1de8deb75b Mon Sep 17 00:00:00 2001
From: Svetlana Karslioglu <svekars@meta.com>
Date: Thu, 24 Apr 2025 18:40:42 +0000
Subject: [PATCH] Update docs dependencies for local build (#151796)

Fixes #151786

- Changed requirements.txt to a symlink to .ci/docker/requirements-docs.txt
- Updated README.md with better doc build instructions.

Pull Request resolved: https://github.com/pytorch/pytorch/pull/151796
Approved by: https://github.com/malfet
---
 README.md             | 37 +++++++++++++++++++++++++++++--------
 docs/requirements.txt | 16 +---------------
 2 files changed, 30 insertions(+), 23 deletions(-)
 mode change 100644 => 120000 docs/requirements.txt

diff --git a/README.md b/README.md
index 2607221cf43..58327c176f3 100644
--- a/README.md
+++ b/README.md
@@ -423,8 +423,19 @@ make -f docker.Makefile
 
 ### Building the Documentation
 
-To build documentation in various formats, you will need [Sphinx](http://www.sphinx-doc.org) and the
-readthedocs theme.
+To build documentation in various formats, you will need [Sphinx](http://www.sphinx-doc.org)
+and the pytorch_sphinx_theme2.
+
+
+
+Before you build the documentation locally, ensure `torch` is
+installed in your environment. For small fixes, you can install the
+nightly version as described in [Getting Started](https://pytorch.org/get-started/locally/).
+
+For more complex fixes, such as adding a new module and docstrings for
+the new module, you might need to install torch [from source](#from-source).
+See [Docstring Guidelines](https://github.com/pytorch/pytorch/wiki/Docstring-Guidelines)
+for docstring conventions.
 
 ```bash
 cd docs/
@@ -438,12 +449,22 @@ Run `make` to get a list of all available output formats.
 If you get a katex error run `npm install katex`.  If it persists, try
 `npm install -g katex`
 
-> Note: if you installed `nodejs` with a different package manager (e.g.,
-`conda`) then `npm` will probably install a version of `katex` that is not
-compatible with your version of `nodejs` and doc builds will fail.
-A combination of versions that is known to work is `node@6.13.1` and
-`katex@0.13.18`. To install the latter with `npm` you can run
-```npm install -g katex@0.13.18```
+> [!NOTE]
+> If you installed `nodejs` with a different package manager (e.g.,
+> `conda`) then `npm` will probably install a version of `katex` that is not
+> compatible with your version of `nodejs` and doc builds will fail.
+> A combination of versions that is known to work is `node@6.13.1` and
+> `katex@0.13.18`. To install the latter with `npm` you can run
+> ```npm install -g katex@0.13.18```
+
+> [!NOTE]
+> If you see a numpy incompatibility error, run:
+> ```
+> pip install 'numpy<2'
+> ```
+
+When you make changes to the dependencies run by CI, edit the
+`.ci/docker/requirements-docs.txt` file.
 
 ### Previous Versions
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
deleted file mode 100644
index fa9da6bf059..00000000000
--- a/docs/requirements.txt
+++ /dev/null
@@ -1,15 +0,0 @@
-sphinx==5.3.0
--e git+https://github.com/pytorch/pytorch_sphinx_theme.git@pytorch_sphinx_theme2#egg=pytorch_sphinx_theme2
-# TODO: sphinxcontrib.katex 0.9.0 adds a local KaTeX server to speed up pre-rendering
-# but it doesn't seem to work and hangs around idly. The initial thought is probably
-# something related to Docker setup. We can investigate this later
-sphinxcontrib.katex==0.8.6
-matplotlib==3.6.0
-tensorboard==2.10.0
-# required to build torch.distributed.elastic.rendezvous.etcd* docs
-python-etcd==0.4.5
-sphinx-copybutton==0.5.0
-myst-parser==0.18.1
-sphinx-design==0.4.0
-sphinxcontrib-mermaid==1.0.0
-sphinxext-opengraph==0.9.1
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 120000
index 00000000000..7176089000a
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1 @@
+../.ci/docker/requirements-docs.txt
\ No newline at end of file