Fixing regressions in pdf documentation building

docs/Makefile

@@ -5,9 +5,7 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = build
-# The below doesn't seem to work properly....  changed to 'build' directory (above) within the docs folder
-# BUILDDIR      = /tmp/TemoaDocumentationBuild
+BUILDDIR      = _build
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -108,9 +106,22 @@ latex:
 latexpdf:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex \
-	  LATEXOPTS='-interaction=nonstopmode -file-line-error -halt-on-error' \
-	  all-pdf
+	@if command -v latexmk > /dev/null 2>&1; then \
+		$(MAKE) -C $(BUILDDIR)/latex \
+			LATEXOPTS='-interaction=nonstopmode -file-line-error -halt-on-error' \
+			all-pdf; \
+	else \
+		echo "latexmk not found, falling back to manual pdflatex..."; \
+		$(MAKE) -C $(BUILDDIR)/latex \
+			PDFLATEX="pdflatex -interaction=nonstopmode -file-line-error -halt-on-error" \
+			LATEXMKOPTS="" \
+			all-pdf || true; \
+		echo "Running pdflatex again for references..."; \
+		$(MAKE) -C $(BUILDDIR)/latex \
+			PDFLATEX="pdflatex -interaction=nonstopmode -file-line-error -halt-on-error" \
+			LATEXMKOPTS="" \
+			all-pdf; \
+	fi
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 text:
@@ -156,4 +167,3 @@ doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
-

docs/README.md

@@ -41,14 +41,14 @@ The generated HTML files will be in `docs/_build/html/`. Open `index.html` in yo
 
 ### Generating PDF Documentation
 
-To generate PDF documentation, you'll need LaTeX installed on your system:
+To generate PDF documentation, you'll need LaTeX installed. latexmk is recommended for automatic PDF generation:
 - **macOS**: [MacTeX](https://www.tug.org/mactex/mactex-download.html)
-- **Windows/Linux**: [MiKTeX](https://miktex.org/download)
+- **Windows/Linux**: [MiKTeX](https://miktex.org/download) or TeX Live
 
 Then run:
 
 ```bash
-uv run sphinx-build -b latexpdf source _build/latex
+uv run make latexpdf
 ```
 
 The PDF will be generated in `docs/_build/latex/`.

docs/source/Documentation.rst

@@ -77,7 +77,7 @@ The interactive HTML network graphs provide dynamic exploration with pan, zoom,
 
 Graphviz also generates static SVG diagrams showing the energy system structure:
 
-.. figure:: images/graphviz_examples/results1990.svg
+.. figure:: images/results1990.*
    :align: center
    :figclass: center
    :width: 100%

docs/source/computational_implementation.rst

@@ -378,18 +378,18 @@ The Temoa model code is organized into clear, purpose-driven packages:
 
 * ``temoa.data_processing`` - Output analysis and visualization
 
-  * ``db_to_excel.py`` - Excel output generation (⚠️ untested in v4.0)
-  * ``make_graphviz.py`` - Network diagram generation (⚠️ untested in v4.0)
+  * ``db_to_excel.py`` - Excel output generation ([!] untested in v4.0)
+  * ``make_graphviz.py`` - Network diagram generation ([!] untested in v4.0)
   * Result processing utilities
 
 * ``temoa.extensions`` - Optional extensions for advanced analysis
 
-  * ``modeling_to_generate_alternatives`` - MGA analysis for exploring near-optimal solutions (⚠️ untested in v4.0)
-  * ``method_of_morris`` - Sensitivity analysis (⚠️ untested in v4.0)
-  * ``monte_carlo`` - Uncertainty quantification (⚠️ untested in v4.0)
+  * ``modeling_to_generate_alternatives`` - MGA analysis for exploring near-optimal solutions ([!] untested in v4.0)
+  * ``method_of_morris`` - Sensitivity analysis ([!] untested in v4.0)
+  * ``monte_carlo`` - Uncertainty quantification ([!] untested in v4.0)
   * ``myopic`` - Sequential decision making with limited foresight
-  * ``single_vector_mga`` - Focused MGA on specific variables (⚠️ untested in v4.0)
-  * ``stochastics`` - Stochastic programming capabilities (⚠️ untested in v4.0)
+  * ``single_vector_mga`` - Focused MGA on specific variables ([!] untested in v4.0)
+  * ``stochastics`` - Stochastic programming capabilities ([!] untested in v4.0)
 
 * ``temoa._internal`` - Internal utilities (not part of public API)
 

docs/source/mathematical_formulation.rst

@@ -1064,7 +1064,7 @@ calculated via the formula:
 
    LA_{t,v} = \frac{DR_{r,t,v}}{1 - (1 + DR_{r,t,v})^{{}^- LLN_{r,t,v}}}
 
-   \forall \{t, v\} \in \Theta_\text{cost_invest}
+   \forall \{t, v\} \in \Theta_{\text{cost\_invest}}
 
 
 model_process_life

docs/source/quick_start.rst

@@ -164,7 +164,7 @@ table, it will fail with an error. This foreign key reference ensures that the
 modeler doesn't accidently type the wrong label in this table. For context,
 there are two basic types of time periods in Temoa, ``e``, which defines
 pre-existing periods, and ``f``, which defines future time periods that are to
-be optimized. 
+be optimized.
 
 This enforcement of names across tables using foreign keys helps immediately
 catch typos. As you can imagine, typos happen in plain text files and Excel when

docs/source/unit_checking.rst

@@ -100,10 +100,10 @@ Units in **efficiency** and **cost** tables MUST use ratio format:
 
    Numerator / (Denominator)
 
-   ✅ CORRECT:   PJ / (PJ)
-   ✅ CORRECT:   Mdollar / (PJ^2 / GW)
-   ❌ WRONG:     PJ/PJ              (no parentheses)
-   ❌ WRONG:     Mdollar * GW / (PJ^2)   (denominator incomplete)
+   [V] CORRECT:   PJ / (PJ)
+   [V] CORRECT:   Mdollar / (PJ^2 / GW)
+   [X] WRONG:     PJ/PJ              (no parentheses)
+   [X] WRONG:     Mdollar * GW / (PJ^2)   (denominator incomplete)
 
 The denominator **MUST be fully enclosed in parentheses**. The regex only captures content
 within ``( )`` after the ``/``.
@@ -112,10 +112,10 @@ Other tables should use plain entries:
 
 .. code-block:: text
 
-   ✅  PJ
-   ✅  petajoules
-   ✅  GW
-   ✅  Mt / (GW)    (if ratio needed)
+   [V]  PJ
+   [V]  petajoules
+   [V]  GW
+   [V]  Mt / (GW)    (if ratio needed)
 
 Custom Units Registry
 ~~~~~~~~~~~~~~~~~~~~~
@@ -138,15 +138,15 @@ Common Footguns and Pitfalls
 
 .. code-block:: text
 
-   ❌ cost_invest units: "Mdollar / PJ^2 / GW"
+   [X] cost_invest units: "Mdollar / PJ^2 / GW"
 
    Error: RATIO_ELEMENT regex doesn't match, only "PJ^2" captured
 
 **Solution**: Always use parentheses
 
 .. code-block:: text
 
-   ✅ cost_invest units: "Mdollar / (PJ^2 / GW)"
+   [V] cost_invest units: "Mdollar / (PJ^2 / GW)"
 
 2. Capacity vs Energy Units
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -155,20 +155,20 @@ Common Footguns and Pitfalls
 
 .. code-block:: text
 
-   ❌ existing_capacity units: "GW * year"
+   [X] existing_capacity units: "GW * year"
 
    Error: Energy units (not capacity) in capacity table
 
 **Solution**: Use power units (negative time dimension)
 
 .. code-block:: text
 
-   ✅ existing_capacity units: "GW"    ([time]^-3 = power)
-   ❌ existing_capacity units: "GWh"   ([time]^-2 = energy)
+   [V] existing_capacity units: "GW"    ([time]^-3 = power)
+   [X] existing_capacity units: "GWh"   ([time]^-2 = energy)
 
 **Physics**:
-- Capacity = Power (W, kW, MW, GW) → ``[time]^-3``
-- Energy = Power × Time (Wh, kWh) → ``[time]^-2``
+- Capacity = Power (W, kW, MW, GW) -> ``[time]^-3``
+- Energy = Power × Time (Wh, kWh) -> ``[time]^-2``
 
 3. Cost Table Units and C2A
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -179,7 +179,7 @@ For capacity-based costs, the expected denominator is:
 
 .. math::
 
-   \text{expected_measure} = \text{output_units} \times \text{C2A} \times \text{year}
+   \text{expected\_measure} = \text{output\_units} \times \text{C2A} \times \text{year}
 
 **Example**:
 - Output commodity: ``ELC`` = ``PJ``
@@ -188,8 +188,8 @@ For capacity-based costs, the expected denominator is:
 
 .. code-block:: text
 
-   ✅ cost_invest: "Mdollar / (PJ^2 / GW)"
-   ✅ cost_fixed:  "Mdollar / (PJ^2 / GW / year)"   (adds /year for period-based)
+   [V] cost_invest: "Mdollar / (PJ^2 / GW)"
+   [V] cost_fixed:  "Mdollar / (PJ^2 / GW / year)"   (adds /year for period-based)
 
 4. period_based Flag
 ~~~~~~~~~~~~~~~~~~~~
@@ -241,11 +241,11 @@ Tables affected: ``limit_activity``, ``limit_capacity``, ``limit_new_capacity``
 
 .. code-block:: text
 
-   ❌ WRONG:
+   [X] WRONG:
    tech E01, output ELC: PJ
    tech E01, output HEAT: GJ    (different units!)
 
-   ✅ CORRECT:
+   [V] CORRECT:
    tech E01, output ELC: PJ
    tech E01, output HEAT: PJ    (same units)
 
@@ -278,16 +278,16 @@ Common Error Messages
 .. code-block:: text
 
    "Units lack currency dimension"
-   → Cost table units don't contain currency (dollar/euro)
+   -> Cost table units don't contain currency (dollar/euro)
 
    "Energy units (not capacity) in capacity table"
-   → Using energy units (kWh, GWh, etc.) instead of capacity units (GW, MW)
+   -> Using energy units (kWh, GWh, etc.) instead of capacity units (GW, MW)
 
    "Non-matching measure unit"
-   → Units don't match expected format after accounting for C2A/period
+   -> Units don't match expected format after accounting for C2A/period
 
    "failed to process query: no such column: tech"
-   → Using old SQL queries on v4.0 schema (should auto-fix now)
+   -> Using old SQL queries on v4.0 schema (should auto-fix now)
 
 Reading Unit Check Reports
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -329,28 +329,28 @@ v4.0 Schema Coverage
    :header: "Table", "Has Units", "Check 2", "Check 3", "Check 4", "Check 5"
    :widths: 25, 12, 10, 12, 15, 10
 
-   "capacity_to_activity", "✓", "✓", "", "(used)", "(used)"
-   "commodity", "✓", "✓", "✓", "", ""
-   "construction_input", "✓", "✓", "", "", ""
-   "cost_emission", "✓", "✓", "", "", "✓"
-   "cost_fixed", "✓", "✓", "", "", "✓"
-   "cost_invest", "✓", "✓", "", "", "✓"
-   "cost_variable", "✓", "✓", "", "", "✓"
-   "demand", "✓", "✓", "", "✓", ""
-   "efficiency", "✓", "✓", "✓", "", ""
-   "emission_activity", "✓", "✓", "", "", ""
-   "emission_embodied", "✓", "✓", "", "", ""
-   "emission_end_of_life", "✓", "✓", "", "", ""
-   "end_of_life_output", "✓", "✓", "", "", ""
-   "existing_capacity", "✓", "✓", "", "✓", ""
-   "lifetime_process", "✓", "✓", "", "", ""
-   "lifetime_tech", "✓", "✓", "", "", ""
-   "loan_lifetime_process", "✓", "✓", "", "", ""
-   "limit_activity", "✓", "✓", "", "✓", ""
-   "limit_capacity", "✓", "✓", "", "✓", ""
-   "limit_emission", "✓", "✓", "", "", ""
-   "limit_new_capacity", "✓", "✓", "", "✓", ""
-   "limit_resource", "✓", "✓", "", "", ""
+   "capacity_to_activity", "[V]", "[V]", "", "(used)", "(used)"
+   "commodity", "[V]", "[V]", "[V]", "", ""
+   "construction_input", "[V]", "[V]", "", "", ""
+   "cost_emission", "[V]", "[V]", "", "", "[V]"
+   "cost_fixed", "[V]", "[V]", "", "", "[V]"
+   "cost_invest", "[V]", "[V]", "", "", "[V]"
+   "cost_variable", "[V]", "[V]", "", "", "[V]"
+   "demand", "[V]", "[V]", "", "[V]", ""
+   "efficiency", "[V]", "[V]", "[V]", "", ""
+   "emission_activity", "[V]", "[V]", "", "", ""
+   "emission_embodied", "[V]", "[V]", "", "", ""
+   "emission_end_of_life", "[V]", "[V]", "", "", ""
+   "end_of_life_output", "[V]", "[V]", "", "", ""
+   "existing_capacity", "[V]", "[V]", "", "[V]", ""
+   "lifetime_process", "[V]", "[V]", "", "", ""
+   "lifetime_tech", "[V]", "[V]", "", "", ""
+   "loan_lifetime_process", "[V]", "[V]", "", "", ""
+   "limit_activity", "[V]", "[V]", "", "[V]", ""
+   "limit_capacity", "[V]", "[V]", "", "[V]", ""
+   "limit_emission", "[V]", "[V]", "", "", ""
+   "limit_new_capacity", "[V]", "[V]", "", "[V]", ""
+   "limit_resource", "[V]", "[V]", "", "", ""
 
 **Check Legend**:
 - Check 2: Standard validation (format, characters, registry)