Bugfix: Fix the creation of the MET User's Guide PDF

[JohnHalleyGotway]

Describe the Task

RTD has recently begun failing when attempting to render a PDF of the MET User's Guide. On 2/20/23, @JohnHalleyGotway reconfigured RTD to stop creating the PDF to avoid these failures. This task is to investigate/fix the underlying problem and re-enable the PDF builds for both the latest (main_v11.0) and develop branches.

See this RTD build for an example.

Note that the error occurs in this command which is executed after the successful sphinx html and sphinx pdf builds.

latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=met -interaction=nonstopmode

The command above is only executed when building a PDF. Note in particular 2 issues.

1. There are over 100 "errors" which triggers this failure. Apparently 100 is a hard-coded TeX setting. Perhaps, we have SO MANY equations in this doc which produce these "errors" that it triggers this behavior? And it's showing up now because we just crossed over from 99 to 100?

! Missing } inserted.
<inserted text> 
                }
l.38109 ...sum_{i \ne j}|f_{i} - f_{j}|\end{split}
                                                  
(That makes 100 errors; please try again.)
!  ==> Fatal error occurred, no output PDF file produced!

2. 19 references are "unresolved":

Latexmk: List of undefined refs and citations:
  Reference `Users_Guide/appendixC:app-c-distance-maps' on page 219 undefined on input line 16395
  Reference `Users_Guide/appendixC:app-c-gbeta' on page 220 undefined on input line 16401
  Reference `Users_Guide/appendixD:app-d-confidence-intervals' on page 183 undefined on input line 12374
  Reference `Users_Guide/appendixD:app-d-confidence-intervals' on page 384 undefined on input line 30835
  Reference `Users_Guide/appendixD:appendixd' on page 191 undefined on input line 12623
  Reference `Users_Guide/appendixD:appendixd' on page 215 undefined on input line 16304
  Reference `Users_Guide/appendixD:appendixd' on page 3 undefined on input line 169
  Reference `Users_Guide/appendixF:appendixf' on page 150 undefined on input line 10610
  Reference `Users_Guide/appendixF:appendixf' on page 19 undefined on input line 893
  Reference `Users_Guide/appendixF:appendixf' on page 21 undefined on input line 1035
  Reference `Users_Guide/appendixF:appendixf' on page 290 undefined on input line 22920
  Reference `Users_Guide/appendixF:pyembed-point-obs-data' on page 138 undefined on input line 9574
  Reference `Users_Guide/appendixF:pyembed-point-obs-data' on page 149 undefined on input line 10502
  Reference `Users_Guide/appendixF:pyembed-point-obs-data' on page 193 undefined on input line 12781
  Reference `Users_Guide/appendixF:pyembed-point-obs-data' on page 194 undefined on input line 12796
  Reference `Users_Guide/appendixF:pyembed-point-obs-data' on page 241 undefined on input line 18281
  Reference `Users_Guide/appendixF:pyembed-point-obs-data' on page 420 undefined on input line 33298
  Reference `Users_Guide/appendixF:pyembed-point-obs-data' on page 420 undefined on input line 33367
Latexmk: Summary of warnings:
  Latex failed to resolve 19 reference(s)

I checked the METplus build and see none of these warning messages.

Time Estimate

Estimate the amount of work required here.
Issues should represent approximately 1 to 3 days of work.

Sub-Issues

Consider breaking the task down into sub-issues.
None needed.

Relevant Deadlines

List relevant project deadlines here or state NONE.

Funding Source

Define the source of funding and account keys here or state NONE.

Define the Metadata

Assignee

• Select engineer(s) or no engineer required: Julie
• Select scientist(s) or no scientist required

Labels

• Select component(s)
• Select priority
• Select requestor(s)

Projects and Milestone

• Select Repository and/or Organization level Project(s) or add alert: NEED PROJECT ASSIGNMENT label
• Select Milestone as the next official version or Future Versions

Define Related Issue(s)

Consider the impact to the other METplus components.

• METplus, MET, METdataio, METviewer, METexpress, METcalcpy, METplotpy
  No impacts

Task Checklist

See the METplus Workflow for details.

• Complete the issue definition above, including the Time Estimate and Funding Source.
• Fork this repository or create a branch of develop.
  Branch name: feature_<Issue Number>_<Description>
• Complete the development and test your changes.
• Add/update log messages for easier debugging.
• Add/update unit tests.
• Add/update documentation.
• Push local changes to GitHub.
• Submit a pull request to merge into develop.
  Pull request: feature <Issue Number> <Description>
• Define the pull request metadata, as permissions allow.
  Select: Reviewer(s) and Development issues
  Select: Repository level development cycle Project for the next official release
  Select: Milestone as the next official version
• Iterate until the reviewer(s) accept and merge your changes.
• Delete your fork or branch.
• Close this issue.

[jprestop]

From this RTD build page, the last successful build of develop with a PDF was on 09/09/23 and the first failed build of develop with a PDF was on 09/13/22.

[JohnHalleyGotway]

I'm trying to replicate the PDF creation failure on my Mac to make this easier to debug. In order to do so, I had to install several packages via MacPorts. Most are related to latex and texlive fonts (latexmk, texlive-*):

cd docs
make clean latexpdf

Was finally able to replicate the errors reported by RTD:

(That makes 100 errors; please try again.)
!  ==> Fatal error occurred, no output PDF file produced!
...
Latexmk: Summary of warnings from last run of *latex:
  Latex failed to resolve 534 reference(s)

Note that removing appendixC from index.rst enables the PDF to be created. That proves that its the content in appendixC that's preventing the successful creation of the PDF.

[JohnHalleyGotway]

The underlying problem that triggers all those "errors" and subsequent PDF failure is the use of embedding underscores (_) inside \text{} formatting for math equations, such as:

.. math:: \text{crps_emp_fair}_i = \text{crps_emp}_i - \frac{1}{2*m} *  \frac{1}{m*(m-1)} \sum_{i \neq j}|f_{i} - f_{j}|

For LaTeX, and thus PDF, those underscores inside \text{} need to be escaped with a backslash ()... but only for LaTeX, not HTML. While there may be multiple ways to solve this issue, it's handled in the rest of Appendix C by specifying equations separately for the two targets.

.. only:: latex

  .. math:: \text{crps\_emp\_fair}_i = \text{crps\_emp}_i - \frac{1}{2*m} *  \frac{1}{m*(m-1)} \sum_{i \neq j}|f_{i} - f_{j}|

.. only:: html

  .. math:: \text{crps_emp_fair}_i = \text{crps_emp}_i - \frac{1}{2*m} *  \frac{1}{m*(m-1)} \sum_{i \neq j}|f_{i} - f_{j}|

After making that change to a few equations, both the HTML and PDF builds are working well again.