Fix recursive \printindex causing blank/duplicate index sections in PDF build

[Copilot]

docs/source/indices.rst contained a self-referential \renewcommand{\printindex} that called itself recursively, producing two index sections in the PDF — one with ~2 blank pages and another with ~4000 blank pages.

Changes

• docs/source/indices.rst: Replace the recursive \renewcommand block with a plain \printindex under .. only:: latex:

  .. only:: latex
  
      Index
      =====
  
      .. raw:: latex
  
          \printindex

• docs/source/conf.py: Add 'printindex': '' to latex_elements to suppress Sphinx's automatic index insertion at the end of the document — preventing the second duplicate index section that Sphinx appends by default:

  'printindex': '',  # index printed explicitly in indices.rst

HTML output is unaffected; the .. only:: html block in indices.rst is unchanged.

Original prompt

Create a new PR in AdvancedPhotonSource/GSAS-II to fix PDF index generation for the larger developer manual (docs under docs/source/).

Context / current behavior:

• Current date: 2026-03-23.
• The prior fix for empty PDF index was merged as PR Fix empty index in PDF docs for both developer and scripting manuals #317 and then reverted by PR Revert "Fix empty index in PDF docs for both developer and scripting manuals" #318. As of commit 40584678e4d10cf7ceda37e0f2865e1db2e1ebf2 on main, docs/source/indices.rst again contains a recursive LaTeX redefinition of \printindex:

  \renewcommand{\printindex}{%
    \begin{theindex}
    \printindex
    \end{theindex}
  }
  

  This can cause runaway recursion / huge blank index output.
• User reports that after the previous attempt, the PDF contained two index sections, one with ~2 blank pages and another with ~4000 blank pages.
• We should focus ONLY on the larger manual (docs/source/*) for now.

Inputs (current files on main):

• docs/source/index.rst includes indices.rst in its main toctree.
• docs/source/indices.rst currently has the recursive \renewcommand{\printindex}{...\printindex...} block (bad).
• docs/source/conf.py currently does NOT set latex_elements['printindex'] (it was removed by revert PR Revert "Fix empty index in PDF docs for both developer and scripting manuals" #318).

Goal:

• Produce a PDF with exactly one index section, with real index entries (not blank pages).
• Avoid duplicate printing of index (Sphinx auto-appended index + manual index page).
• Avoid any recursive definition of \printindex.
• Keep HTML output unchanged.

Required changes:

1. In docs/source/indices.rst, remove the recursive \renewcommand{\printindex}{...} and replace with a simple explicit index print for LaTeX builds:
   • Use .. only:: latex and .. raw:: latex with a single \printindex line.
   • Keep the existing HTML-only links as-is.
2. In docs/source/conf.py, set latex_elements['printindex'] = '' with a comment explaining this suppresses Sphinx’s auto-added \printindex at end, so that the index is printed only where indices.rst places it.
3. Confirm there are no other \printindex insertions under docs/source/ that would cause duplicate indices.
4. (Optional, only if needed to actually populate index entries) Add a hidden toctree entry for genindex in docs/source/index.rst so LaTeX builder reliably generates the index. If this is added, keep it hidden so HTML navigation is unchanged.

Validation:

• Ensure make latexpdf (or RTD PDF build) results in one index section and does not explode in size.
• Ensure HTML build still works.

Out of scope:

• Do not change docs/scripting/* in this PR.
• Do not change unrelated files like docs/environment.yml.

Reference:

• Main branch currently at commit 40584678e4d10cf7ceda37e0f2865e1db2e1ebf2.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Please continue the work on #317 with PR #318 but note that the index is not being created correctly as noted at the end of the previous session

Assistant: I can’t continue yet because there’s a pending confirmation/authorization step from the previous session that has to be accepted (or rejected) before I’m able to apply any further changes to PR #318 or update the docs to fix the index-generation problem.

User: @copilot Dismissed Confirmation: Are you sure?

Assistant: Got it — that dismissed call would also have made the situation worse: setting latex_elements['printindex'] to True is not a valid/usable value for Sphinx (it must be a LaTeX string, and in GSAS-II we intentionally set it to '' to prevent Sphinx from auto-inserting \\printindex at the end).

User: I still would like to generate an index in the .pdf document. For now lets concentrate on the larger manual from the files in doc/source

Assistant: To get a non-empty index in the PDF for the larger manual (docs/source/*), you want two things to be true at the same time:

1. Sphinx must create the index files (the .idx / .ind content via makeindex/xindy) and populate them (this happens when genindex is enabled and there are indexable terms).
2. LaTeX must print that index somewhere in the document (that’s \printindex), and it must not be suppressed or accidentally turned into a no-op.

Right now, on main (commit a6eb29bc...), you already have the right overall structure for #2:

• docs/source/index.rst includes indices.rst in the toctree.
• docs/source/indices.rst includes a .. only:: latex block that does \printindex.
• docs/source/conf.py sets latex_elements['printindex'] = '' which suppresses Sphinx’s automatic “print the index at the end of the PDF”, but still allows your explicit \printindex inside indices.rst to control placement.

So if the PDF index is still “not being created correctly”, the likely failure is #1: the index is being printed, but it contains no entries because genindex isn’t being generated/populated for LaTeX, or because makeindex/xindy isn’t being run.

What I recommend changing (docs/source only)

A) Explici...

This pull request was created from Copilot chat.

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.