Merge pull request Pyomo#3495 from jsiirola/sphinx-pdf

Resolve errors building documentation PDF
mrmundt · Mar 3, 2025 · 1177d93 · 1177d93
2 parents fc7e91a + eb7abbd
commit 1177d93
Show file tree

Hide file tree

Showing 25 changed files with 431 additions and 219 deletions.
diff --git a/.github/workflows/test_branches.yml b/.github/workflows/test_branches.yml
@@ -78,24 +78,26 @@ jobs:
         include:
         - os: ubuntu-latest
           python: 3.13
+          test_docs: 1
           TARGET: linux
           PYENV: pip
 
         - os: macos-latest
           python: 3.12
+          test_docs: 1
           TARGET: osx
           PYENV: pip
 
         - os: windows-latest
           python: 3.11
+          test_docs: 1
           TARGET: win
           PYENV: conda
           PACKAGES: glpk pytest-qt filelock
 
         - os: ubuntu-latest
           python: 3.11
           other: /conda
-          skip_doctest: 1
           TARGET: linux
           PYENV: conda
           PACKAGES: pytest-qt
@@ -104,7 +106,6 @@ jobs:
           python: '3.10'
           other: /mpi
           mpi: 3
-          skip_doctest: 1
           TARGET: linux
           PYENV: conda
           PACKAGES: openmpi mpi4py
@@ -113,15 +114,13 @@ jobs:
           python: 3.12
           other: /cython
           setup_options: --with-cython
-          skip_doctest: 1
           TARGET: linux
           PYENV: pip
           PACKAGES: cython
 
         - os: windows-latest
           python: 3.9
           other: /pip
-          skip_doctest: 1
           TARGET: win
           PYENV: pip
 
@@ -671,7 +670,7 @@ jobs:
             > ${SITE_PACKAGES}/run_coverage_at_startup.pth
 
     - name: Download and install extensions
-      if: ${{ ! matrix.slim }}
+      if: ${{ ! matrix.slim && matrix.category != 'notests' }}
       run: |
         echo ""
         echo "Pyomo download-extensions"
@@ -695,7 +694,7 @@ jobs:
         pyomo help --writers || exit 1
 
     - name: Run Pyomo tests
-      if: matrix.mpi == 0
+      if: ${{ matrix.mpi == 0 && matrix.category != 'notests' }}
       run: |
         export PATH=$PYOMO_PATH
         $PYTHON_EXE -m pytest -v \
@@ -704,7 +703,7 @@ jobs:
             `pwd`/examples `pwd`/doc --junitxml="TEST-pyomo.xml"
 
     - name: Run Pyomo MPI tests
-      if: matrix.mpi != 0
+      if: ${{ matrix.mpi != 0 && matrix.category != 'notests' }}
       run: |
         # Manually invoke the DAT parser so that parse_table_datacmds.py
         # is fully generated by a single process before invoking MPI
@@ -716,8 +715,16 @@ jobs:
             -m "mpi" -W ignore::Warning \
             pyomo `pwd`/pyomo-model-libraries
 
+    - name: Build documentation
+      if: matrix.build_docs != 0
+      run: |
+        sudo apt-get -y install graphviz latexmk texlive texlive-latex-extra \
+            texlive-pictures
+        make -C doc/OnlineDocs html
+        make -C doc/OnlineDocs latexpdf
+
     - name: Run documentation tests
-      if: matrix.skip_doctest == 0
+      if: matrix.test_docs != 0
       run: |
         make -C doc/OnlineDocs doctest -d
 

diff --git a/.github/workflows/test_pr_and_main.yml b/.github/workflows/test_pr_and_main.yml
@@ -74,22 +74,24 @@ jobs:
 
         include:
         - os: ubuntu-latest
+          test_docs: 1
           TARGET: linux
           PYENV: pip
 
         - os: macos-latest
+          test_docs: 1
           TARGET: osx
           PYENV: pip
 
         - os: windows-latest
+          test_docs: 1
           TARGET: win
           PYENV: conda
           PACKAGES: glpk pytest-qt filelock
 
         - os: ubuntu-latest
           python: 3.11
           other: /conda
-          skip_doctest: 1
           TARGET: linux
           PYENV: conda
           PACKAGES: pytest-qt
@@ -98,7 +100,6 @@ jobs:
           python: '3.10'
           other: /mpi
           mpi: 3
-          skip_doctest: 1
           TARGET: linux
           PYENV: conda
           PACKAGES: openmpi mpi4py
@@ -107,39 +108,34 @@ jobs:
           python: 3.12
           other: /cython
           setup_options: --with-cython
-          skip_doctest: 1
           TARGET: linux
           PYENV: pip
           PACKAGES: cython
 
         - os: windows-latest
           python: 3.9
           other: /pip
-          skip_doctest: 1
           TARGET: win
           PYENV: pip
 
         - os: ubuntu-latest
           python: 3.11
           other: /singletest
           category: "-m 'neos or importtest'"
-          skip_doctest: 1
           TARGET: linux
           PYENV: pip
 
         - os: ubuntu-latest
           python: 3.9
           other: /slim
           slim: 1
-          skip_doctest: 1
           TARGET: linux
           PYENV: pip
 
         - os: ubuntu-latest
           python: 3.12
           other: /numpy2
           slim: 1
-          skip_doctest: 1
           TARGET: linux
           PYENV: pip
           PACKAGES: "gurobipy dill numpy>2.0 scipy networkx"
@@ -153,10 +149,18 @@ jobs:
 
         - os: ubuntu-latest
           python: 'pypy-3.10'
-          skip_doctest: 1
           TARGET: linux
           PYENV: pip
 
+        - os: ubuntu-latest
+          python: 3.11
+          other: /rtd
+          category: notests
+          build_docs: 1
+          TARGET: linux
+          PYENV: pip
+
+
     steps:
     - name: Checkout Pyomo source
       uses: actions/checkout@v4
@@ -703,7 +707,7 @@ jobs:
             > ${SITE_PACKAGES}/run_coverage_at_startup.pth
 
     - name: Download and install extensions
-      if: ${{ ! matrix.slim }}
+      if: ${{ ! matrix.slim && matrix.category != 'notests' }}
       run: |
         echo ""
         echo "Pyomo download-extensions"
@@ -727,7 +731,7 @@ jobs:
         pyomo help --writers || exit 1
 
     - name: Run Pyomo tests
-      if: matrix.mpi == 0
+      if: ${{ matrix.mpi == 0 && matrix.category != 'notests' }}
       run: |
         export PATH=$PYOMO_PATH
         $PYTHON_EXE -m pytest -v \
@@ -736,7 +740,7 @@ jobs:
             `pwd`/examples `pwd`/doc --junitxml="TEST-pyomo.xml"
 
     - name: Run Pyomo MPI tests
-      if: matrix.mpi != 0
+      if: ${{ matrix.mpi != 0 && matrix.category != 'notests' }}
       run: |
         # Manually invoke the DAT parser so that parse_table_datacmds.py
         # is fully generated by a single process before invoking MPI
@@ -748,8 +752,16 @@ jobs:
             -m "mpi" -W ignore::Warning \
             pyomo `pwd`/pyomo-model-libraries
 
+    - name: Build documentation
+      if: matrix.build_docs != 0
+      run: |
+        sudo apt-get -y install graphviz latexmk texlive texlive-latex-extra \
+            texlive-pictures
+        make -C doc/OnlineDocs html
+        make -C doc/OnlineDocs latexpdf
+
     - name: Run documentation tests
-      if: matrix.skip_doctest == 0
+      if: matrix.test_docs != 0
       run: |
         make -C doc/OnlineDocs doctest -d
 

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -9,6 +9,20 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+  apt_packages:
+    - graphviz
+    - latexmk
+    - texlive
+    - texlive-latex-extra
+    - texlive-pictures
+  jobs:
+    post_build:
+      - |
+        for pdf in $READTHEDOCS_OUTPUT/pdf/*.pdf; do
+            if test [[ `basename $pdf` == graphviz* ]]; then
+                rm -v $pdf;
+            fi;
+        done
 
 sphinx:
    configuration: doc/OnlineDocs/conf.py

diff --git a/doc/OnlineDocs/Makefile b/doc/OnlineDocs/Makefile
@@ -22,10 +22,15 @@ help:
 
 clean:
 	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-	@echo "Removing *.spy, *.out"
+	@echo "Removing *.spy"
 	@find . -name \*.spy -delete
 	@for D in $(BUILDDIR) $(SOURCEDIR)/$(APIDIR); do \
 	    if test -d "$$D"; then echo "Removing $$D"; rm -r "$$D"; fi \
 	 done
+	@for D in ext src; do \
+	    if test -d "$$D/__pycache__"; then \
+                echo "Removing $$D/__pycache__"; rm -r "$$D/__pycache__" ; \
+            fi \
+	 done
 
 rebuild: clean html
diff --git a/doc/OnlineDocs/code.rst b/doc/OnlineDocs/code.rst
@@ -1,9 +1,16 @@
 :orphan:
 
+This document is a reference containing all Pyomo module, class, and
+function documentation.
+
 .. autosummary::
    :toctree: api
    :caption: Library Reference
    :template: recursive-module.rst
    :recursive:
 
    pyomo
+
+
+* :ref:`genindex`
+* :ref:`modindex`
diff --git a/doc/OnlineDocs/conf.py b/doc/OnlineDocs/conf.py
@@ -84,6 +84,7 @@
     # Our version of 'autoenum', designed to work with autosummary.
     # This adds 'sphinx.ext.autosummary', and 'sphinx.ext.autodoc':
     'pyomo_autosummary_autoenum',
+    'pyomo_tocref',
 ]
 
 viewcode_follow_imported_members = True
@@ -107,7 +108,7 @@
 # General information about the project.
 project = u'Pyomo'
 copyright = u'2008-2024, Sandia National Laboratories'
-author = u'Pyomo Developers'
+author = u'Pyomo Development Team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -129,7 +130,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
+# These patterns also effect to html_static_path and html_extra_path
 # Notes:
 #  - _build : this is the Sphinx build (output) dir
 #
@@ -208,41 +209,56 @@
     # 'pointsize': '10pt',
     # Additional stuff for the LaTeX preamble.
     #
-    # 'preamble': '',
+    'preamble': r'''
+\usepackage{enumitem}
+\setlistdepth{99}
+\DeclareUnicodeCharacter{2227}{$\wedge$}
+\DeclareUnicodeCharacter{2228}{$\vee$}
+\DeclareUnicodeCharacter{22BB}{$\veebar$}
+''',
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
+    # necessary for unicode charactacters in pdf output
+    'inputenc': '',
+    'utf8extra': '',
+    # remove blank pages (e.g., between chapters)
+    'classoptions': ',openany,oneside',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
-latex_documents = [(master_doc, 'pyomo.tex', 'Pyomo Documentation', 'Pyomo', 'manual')]
+latex_documents = [(master_doc, 'pyomo.tex', 'Pyomo Documentation', author, 'manual')]
+if not on_rtd:
+    latex_documents.append(
+        ('code', 'pyomo_reference.tex', 'Pyomo Code Reference', author, 'manual')
+    )
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+latex_logo = '../logos/pyomo/PyomoNewBlue.jpg'
 
+# Disable the domain indices (i.e., the module index) for LaTeX targets:
+# because we are splitting the documentation, the module index in the
+# main document would be completely broken, and having one in the
+# reference document seems redundant (JDS: and I haven't figured out how
+# to have it in only one of the documents)
+latex_domain_indices = False
 
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, 'pyomo', 'Pyomo Documentation', [author], 1)]
+man_pages = []
 
 
 # -- Options for Texinfo output -------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
-texinfo_documents = [
-    (
-        master_doc,
-        'pyomo',
-        'Pyomo Documentation',
-        author,
-        'Pyomo',
-        'One line description of project.',
-        'Miscellaneous',
-    )
-]
+texinfo_documents = []
 
 # autodoc_member_order = 'bysource'
 autodoc_member_order = 'groupwise'