Improve the Sphinx configs for laTeX/PDF builds

[zwoop]

This also cleans up a bunch of RST and UML formats and files, which should work and improve HTML output as well.

We also try to automate more of the builds, setting up the appropraite pyenv and also making sure we deal with macOS app focus.

Finally, this upgrades PlantUML to v1.2025.10.

[Copilot]

Pull Request Overview

This PR improves the Sphinx documentation build configuration to better support LaTeX/PDF generation while maintaining HTML output quality. The changes include upgrading PlantUML, enhancing image format handling, improving UML diagram integration, and cleaning up RST formatting issues.

• Adds a LaTeX-specific master document (index-latex.rst) for better PDF structure
• Updates image references to use conditional directives for format-specific rendering (SVG for HTML, PNG for LaTeX)
• Converts hardcoded UML image references to use PlantUML directives for dynamic generation
• Refactors version detection in the Sphinx extension to use CMakeLists.txt instead of configure.ac
• Fixes broken RST references and removes trailing blank lines

Reviewed Changes

Copilot reviewed 22 out of 25 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
doc/static/images/admin/transaction_states_timers.png	Binary PNG image added for LaTeX/PDF builds
doc/index-latex.rst	New LaTeX-specific master document with structured table of contents for PDF generation
doc/ext/traffic-server.py	Refactored version detection to use CMakeLists.txt; improved formatting; added error handling for git commands
doc/ext/local-config.cmake.in.py	Added plantuml_latex_output_format configuration for PNG output in LaTeX
doc/developer-guide/plugins/hooks-and-transactions/trafficserver-timers.en.rst	Added conditional directives for SVG (HTML) and PNG (LaTeX) image formats
doc/developer-guide/plugins/example-plugins/tls_bridge.en.rst	Converted hardcoded SVG image references to UML directives
doc/developer-guide/jsonrpc/traffic_ctl-development.en.rst	Converted hardcoded SVG image reference to UML directive with alignment
doc/developer-guide/jsonrpc/jsonrpc-handler-development.en.rst	Converted SVG reference to UML directive; removed trailing blank lines
doc/developer-guide/documentation/building.en.rst	Comprehensive update of documentation build instructions for CMake workflow
doc/developer-guide/core-architecture/url_rewrite_architecture.en.rst	Converted SVG reference to UML directive
doc/developer-guide/core-architecture/hostdb.en.rst	Added conditional directives for SVG/PNG format selection
doc/developer-guide/core-architecture/heap.en.rst	Converted SVG references to UML directives with alignment
doc/developer-guide/core-architecture/HostDB-Data-Layout.png	Binary PNG image added for LaTeX/PDF builds
doc/developer-guide/cache-architecture/architecture.en.rst	Added conditional directives for two diagrams (span-header and stripe-header)
doc/admin-guide/tools/converting-records-to-yaml.en.rst	Removed trailing blank line
doc/admin-guide/plugins/lua.en.rst	Fixed broken inline HTML links to use proper RST references
doc/admin-guide/layer-4-routing.en.rst	Converted UML SVG references to directives; improved caption formatting
doc/admin-guide/configuration/hrw4u.en.rst	Updated hrw4u version number from 1.0.0 to 1.4.0; added documentation for new tools
doc/.gitignore	Added conf.py to ignore list (generated file)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bneradt]

Looks great. See my comment below. I have a question about the alignment of a lot of these. But you're usually not changing it in this PR (maye once or twice). Maybe in a separate PR make these left aligned? I'm curious to have your thoughts about this.

[bneradt]

This looks good. We can deal with the alignment issues as a separate PR.

[bneradt]

Looks great. I'm happy with how you got the centering to work on these.