From e58c73be446b42d38b197f7e5dd69ec4ba78200a Mon Sep 17 00:00:00 2001
From: Svetlana Karslioglu <svekars@meta.com>
Date: Tue, 29 Apr 2025 19:28:38 +0000
Subject: [PATCH] Add latex settings (#152350)

- Fixes #147027
- Only lualatex can build our 3K pages PDF with reasonable quality, xelatex runs out of memory and pdflatex just fails.
- Move notes under the same toctree as python-api which is needed for the PDF but doesn't change how the HTML is generated.

This is the produced PDF:
[pytorch.pdf](https://github.com/user-attachments/files/19945450/pytorch.pdf)

Pull Request resolved: https://github.com/pytorch/pytorch/pull/152350
Approved by: https://github.com/albanD
---
 README.md            | 37 +++++++++++++++++++++++++++++++++++--
 docs/source/conf.py  | 34 ++++++++++++++++++++++------------
 docs/source/index.md |  6 ------
 3 files changed, 57 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 47841da7368..17bc2fe659a 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,7 @@ Our trunk health (Continuous Integration signals) can be found at [hud.pytorch.o
     - [Using pre-built images](#using-pre-built-images)
     - [Building the image yourself](#building-the-image-yourself)
   - [Building the Documentation](#building-the-documentation)
+    - [Building a PDF](#building-a-pdf)
   - [Previous Versions](#previous-versions)
 - [Getting Started](#getting-started)
 - [Resources](#resources)
@@ -426,8 +427,6 @@ make -f docker.Makefile
 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/).
@@ -466,6 +465,40 @@ If you get a katex error run `npm install katex`.  If it persists, try
 When you make changes to the dependencies run by CI, edit the
 `.ci/docker/requirements-docs.txt` file.
 
+#### Building a PDF
+
+To compile a PDF of all PyTorch documentation, ensure you have
+`texlive` and LaTeX installed. On macOS, you can install them using:
+
+```
+brew install --cask mactex
+```
+
+To create the PDF:
+
+1. Run:
+
+   ```
+   make latexpdf
+   ```
+
+   This will generate the necessary files in the `build/latex` directory.
+
+2. Navigate to this directory and execute:
+
+   ```
+   make LATEXOPTS="-interaction=nonstopmode"
+   ```
+
+   This will produce a `pytorch.pdf` with the desired content. Run this
+   command one more time so that it generates the correct table
+   of contents and index.
+
+> [!NOTE]
+> To view the Table of Contents, switch to the **Table of Contents**
+> view in your PDF viewer.
+
+
 ### Previous Versions
 
 Installation instructions and binaries for previous PyTorch versions may be found
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 1485c80277e..9cb2e6f9a9d 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -44,6 +44,7 @@ import pytorch_sphinx_theme2
 html_theme = "pytorch_sphinx_theme2"
 html_theme_path = [pytorch_sphinx_theme2.get_html_theme_path()]
 
+
 # -- General configuration ------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -3786,24 +3787,32 @@ htmlhelp_basename = "PyTorchdoc"
 
 # -- Options for LaTeX output ---------------------------------------------
 
+latex_engine = "lualatex"
+latex_show_urls = "footnote"
+
 latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
+    "papersize": "letterpaper",
+    "pointsize": "10pt",
+    "tableofcontents": r"\pdfbookmark[0]{Contents}{toc}\tableofcontents",
+    "preamble": r"""
+       \usepackage{tocloft}
+       \setcounter{tocdepth}{3}
+       \setcounter{secnumdepth}{3}
+       % Fix table column widths
+       \renewenvironment{tabulary}{\begin{longtable}{p{0.3\linewidth}p{0.7\linewidth}}}{\end{longtable}}
+
+       % Ensure tables don't overflow
+       \AtBeginEnvironment{tabular}{\sloppy}
+    """,
+    "fncychap": r"\usepackage[Bjornstrup]{fncychap}",
+    "extraclassoptions": "oneside",
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
+
+
 latex_documents = [
     (
         master_doc,
@@ -3813,6 +3822,7 @@ latex_documents = [
         "manual",
     ),
 ]
+latex_use_xindy = False
 
 
 # -- Options for manual page output ---------------------------------------
diff --git a/docs/source/index.md b/docs/source/index.md
index 3d22ddeff08..082d9551a88 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -33,12 +33,6 @@ Features described in this documentation are classified by release status:
 :maxdepth: 2
 
 pytorch-api
-```
-
-```{toctree}
-:glob:
-:maxdepth: 2
-
 notes
 ```