Skip to content

Resolve errors building documentation PDF#3495

Merged
blnicho merged 34 commits intoPyomo:mainfrom
jsiirola:sphinx-pdf
Mar 3, 2025
Merged

Resolve errors building documentation PDF#3495
blnicho merged 34 commits intoPyomo:mainfrom
jsiirola:sphinx-pdf

Conversation

@jsiirola
Copy link
Copy Markdown
Member

@jsiirola jsiirola commented Feb 27, 2025 •
edited by blnicho
Loading

Fixes # .

Summary/Motivation:

The PDF version of the Sphinx documentation broke after the doc reorg; however, RTD wasn't reporting the failure. After a recent update (to RTD and/or Sphinx), RTD is now reporting the PDF failure as a failure.

This PR resolves the LaTeX errors in various math environments throughout the documentation. It also implements a method where the HTML target retains the diataxis tabular format, but uses a linear format for the LaTeX target. In addition, the PDF target is split into two files: the main documentation (~380 pages) and the API reference (~3500 pages).

Changes proposed in this PR:

  • resolve math mode errors in documentation
  • rework the documentation formatting so that the PDF target is rendered linearly (and not in tabular form)
  • add new Sphinx extension for making "TOC references" (so HTML and LaTeX can both have custom TOCs)
  • get unicode support working for RST / docstring inputs
  • remove (likely incorrect / broken) definitions for texinfo and manpage documentation targets

Legal Acknowledgement

By contributing to this software project, I have read the contribution guide and agree to the following terms and conditions for my contribution:

  1. I agree my contributions are submitted under the BSD license.
  2. I represent I am authorized to make the contributions and grant the license. If my employer has rights to intellectual property that includes these contributions, I represent that I have received permission to make contributions and grant the required license on behalf of that employer.

mrmundt
mrmundt requested changes Feb 27, 2025
View reviewed changes
@codecov
Copy link
Copy Markdown

codecov bot commented Feb 27, 2025 •
edited
Loading

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.61%. Comparing base (ab59eb2) to head (521077a).

Additional details and impacted files 
@@            Coverage Diff             @@
##             main    #3495      +/-   ##
==========================================
- Coverage   88.64%   88.61%   -0.04%     
==========================================
  Files         881      881              
  Lines      100873   100873              
==========================================
- Hits        89421    89384      -37     
- Misses      11452    11489      +37
Flag Coverage Δ
linux 86.08% <ø> (ø)
osx 76.10% <ø> (ø)
other 86.56% <ø> (-0.04%) ⬇️
win 80.98% <ø> (-3.58%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@jsiirola jsiirola requested a review from mrmundt February 28, 2025 00:14
@jsiirola
Copy link
Copy Markdown
Member Author

jsiirola commented Feb 28, 2025

The GHA job to build the RTD PDF is working now. The only failing jobs are the Windows conda jobs (conda infrastructure problem unrelated to this PR).

@jsiirola jsiirola requested review from blnicho and emma58 March 2, 2025 06:39
@jsiirola
Copy link
Copy Markdown
Member Author

jsiirola commented Mar 2, 2025

One note: RTD only supports uploading a single PDF. Right now, this PR separates the generation of the (~370-page) "manual" and (~3500-page) "API reference" PDFs. It is configured to only generate / upload the former on RTD and both everywhere else. It is an open question if we should change this and go back to generating / uploading the single monster PDF to RTD.

@blnicho blnicho merged commit 1177d93 into Pyomo:main Mar 3, 2025
35 checks passed
@blnicho blnicho mentioned this pull request Mar 4, 2025
Draft
@jsiirola jsiirola deleted the sphinx-pdf branch March 24, 2025 19:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@blnicho blnicho blnicho approved these changes

@mrmundt mrmundt mrmundt approved these changes

@emma58 emma58 Awaiting requested review from emma58

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@jsiirola @blnicho @mrmundt @emma58