Fix empty index in PDF docs for both developer and scripting manuals

[Copilot]

The PDF builds on Read the Docs produced an empty index. In docs/source/indices.rst, a \renewcommand{\printindex} block redefined \printindex to call itself recursively, causing LaTeX to produce nothing when Sphinx invoked it at document end. The scripting docs had no LaTeX index section at all.

Changes

• docs/source/indices.rst: Replace broken recursive \renewcommand{\printindex}{...} with a direct \printindex call inside a .. only:: latex block.
• docs/scripting/scrpt-indices.rst: Add a .. only:: latex block with an "Index" heading and \printindex (was missing entirely).
• docs/source/conf.py and docs/scripting/conf.py: Add 'printindex': '' to latex_elements to suppress Sphinx's auto-appended \printindex, avoiding a duplicate index.

The .. only:: latex blocks are invisible to HTML builds, so HTML output is unchanged.

.. only:: latex

    Index
    =====

    .. raw:: latex

        \printindex

Original prompt

Create a pull request in AdvancedPhotonSource/GSAS-II that fixes the Read the Docs PDF output so the generated PDF includes a non-empty index.

Context:

• The HTML docs include an index page, but the PDF download has an empty index.
• Relevant files (at commit dfeda4e77597363ddc5de2f425dedf4d86f96e45):
  • docs/source/conf.py
  • docs/source/index.rst
  • docs/scripting/conf.py
  • docs/scripting/index.rst

What to do:

1. Review the above files and adjust Sphinx configuration and/or toctrees so that the LaTeX/PDF build includes the general index (Sphinx genindex) in the PDF output.
2. Make sure changes apply to both the main developer docs (docs/source/*) and the scripting docs (docs/scripting/*) if both are built on RTD.
3. Avoid adding genindex only inside .. only:: html blocks; it must be included for LaTeX output.
4. Prefer a minimal change that reliably causes the PDF to include a populated index. Consider:
   • adding a hidden toctree entry for genindex
   • ensuring LaTeX printindex is not suppressed by latex_elements
   • optionally creating an explicit genindex.rst wrapper page (if needed for consistent inclusion)
5. Validate locally (or with best-effort reasoning if CI isn’t available) that:
   • HTML build still works
   • LaTeX/PDF build now contains an index section with entries

Deliverables:

• PR with the code changes.
• Include a brief PR description explaining why the index was empty in PDF and how the fix works.

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

User: The sphinx docs generated on Readthedocs have an index as html pages (https://gsas-ii.readthedocs.io/en/latest/) but in the .pdf version of the docs (https://gsas-ii.readthedocs.io/_/downloads/en/latest/pdf/) the index is empty. How do I get an index in the.pdf as well?

Assistant: To get an index in the PDF, you need to (1) ensure Sphinx generates a LaTeX index and (2) ensure the “Index” page is actually included in the LaTeX/PDF build.

On Read the Docs, the HTML “Index” you see is the genindex page. The PDF won’t automatically include that unless your LaTeX build is configured to generate/print it.

1) Add genindex to your master toctree (so it’s included in LaTeX/PDF)

In your Sphinx root document (often index.rst, sometimes contents.rst depending on root_doc/master_doc), add genindex to a toctree that’s included in the build:

.. toctree::
   :maxdepth: 2

   ... your existing docs ...
   genindex

This works because genindex is a built-in Sphinx “special document” you can reference from a toctree. (sphinx-doc.org)

If you don’t want it in the HTML sidebar, you can put it in a hidden toctree:

.. toctree::
   :hidden:

   genindex

2) Make sure LaTeX index generation is enabled

In docs/conf.py, ensure these are not disabling the index:

• latex_domain_indices (controls additional domain indices; general index generation still matters for genindex) (sphinx-doc.org)
• Ensure you’re not overriding LaTeX index hooks in a way that suppresses printing.

Usually the default is fine, but if your config customizes LaTeX heavily, confirm you haven’t removed the index print step. Sphinx exposes LaTeX hooks for makeindex and printindex via latex_elements. (sphinx-doc.org)

For example, you can explicitly force printing the index at the end (only if needed):

latex_elements = {
    "printindex": r"\printindex",
}

(Only do this if your project overrides latex_elements already and accidentally removed it.)

3) Rebuild on Read the Docs and confirm the PDF build log

After pushing the change, re-build the RTD project and check the PDF build output. If the index is still empty, the next most common cause is: your docs don’t contain any index entries (no .. index:: directives, and few/no domains that add index entries). Sphinx will still create an Index section, but it can be effectively empty.

If you want, paste:

• your docs/conf.py LaTeX-related settings (latex_elements, latex_documents, latex_engine, latex_use_xindy, latex_domain_indices)
• your root index.rst (or whatever file contains the top-level toctree)

…and I’ll tell you exactly what to change in GSAS-II’s doc setup.

User: can you review the files @AdvancedPhotonSource/GSAS-II/files/docs/source/conf.py and @AdvancedPhotonSource/GSAS-II/files/docs/source/index.rst as well as @AdvancedPhotonSource/GSAS-II/files/docs/scripting/conf.py and @AdvancedPhotonSource/GSAS-II/files/docs/scripting/index.rst and create a PR with changes?

Assistant: I’ve queued up the pull request creation, but I can’t proceed until you respond to the pending confirmation prompt (accept/rejec...

This pull request was created from Copilot chat.

---

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.

[briantoby]

this looks fine. Advancing to Python 3.13 while making changes