sphinx-doc / sphinx-doc/sphinx

HTML and LaTeX/PDF generation require incompatible uses of DeclareMathOperator*

Open
#11,611 6 comments 0 reactions 1 assignee View on GitHub

@jfbu is already working on this.

Since Aug 17, 2023.

awaiting:response builder:html builder:latex
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

For Sphinx LaTeX/PDF generation to work correctly, I need to the following in my conf.py file:

# Additional stuff for the LaTeX preamble.
'preamble': """\\DeclareMathOperator*{\\argmin}{argmin}
\\DeclareMathOperator*{\\argmax}{argmax}
\\sphinxDUC{2610}{$\square$}
"""

For Sphinx HTML generation to work correctly, I need to put the \DeclareMathOperator inside the individual .. math:: pieces. For example,

.. math::
   \DeclareMathOperator*{\argmin}{argmin}
   {\bf p}^\ast &= \argmin_{{\bf p} \in \mathbb{R}^n} \; c({\bf p}) \\
   \text{such that} \; 0 &\leq v({\bf p}) \leq V \\
                       0 &\leq p_i \leq 1, \; i = 1, \ldots n

If I generate LaTeX using sphinx-build using the HTML configuration (i.e., with \DeclareMathOperator inside the individual .. math:: pieces, I see errors like this when I run latex via make.

$ make
latexmk -pdf -dvi- -ps-  'LiDO.tex'
Rc files read:
  /etc/latexmkrc
  latexmkrc
Latexmk: This is Latexmk, John Collins, 4 Apr. 2023. Version 4.80.
No existing .aux file, so I'll make a simple one, and require run of *latex.
Latexmk: applying rule 'pdflatex'...
Rule 'pdflatex':  Reasons for rerun
Category 'other':
  Rerun of 'pdflatex' forced or previously required

------------
Run number 1 of rule 'pdflatex'
------------
------------
Running 'pdflatex   -recorder  "LiDO.tex"'
------------
This is pdfTeX, Version 3.141592653-2.6-1.40.22 (TeX Live 2021/CVE-2023-32700 patched) (preloaded format=pdflatex)
 restricted \write18 enabled.
... numerous lines deleted...
! LaTeX Error: Can be used only in preamble.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.887 ...        &l_n \leq p_n \leq u_n\end{split}
                                                  
? x

The key line is the !LaTeX Error: Can be used only in preamble.

The generated LaTeX behind this error looks like this:

Consider a generic optimization problem of this sort:
\begin{equation*}
\begin{split}\DeclareMathOperator*{\argmin}{argmin}
{\bf p}^\ast = \argmin_{{\bf p} \, \in \, \mathbb{R}^n} \quad &f({\bf p}) \\
\mathrm{such that} \quad &L_1 \leq g_1({\bf p}) \leq U_1 \\
                    &\cdots \\
                    &L_m \leq g_m({\bf p}) \leq U_m \\
                    &l_1 \leq p_1 \leq u_1 \\
                    &\cdots \\
                    &l_n \leq p_n \leq u_n\end{split}
\end{equation*}

I think LaTeX requires \DeclareMathOperator* to be in the preamble.

The command to invoke sphinx looks like

$ sphinx-build -q -b latex -d ${HOME}/lido/build/clang-build/src/docs/sphinx/_doctrees ${HOME}/lido/src/docs/sphinx ${HOME}/lido/build/clang-build/src/docs/sphinx/html
$ sphinx-build --version
sphinx-build 5.0.2

Ideally, I would like a single set of Sphinx inputs to be able to generate both HTML and LaTeX documentation.

How to Reproduce

Here is index.rst for a simple reproducer:

.. LiDO documentation master file, created by
   sphinx-quickstart on Thu Aug 17 08:19:29 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to LiDO's documentation!
================================

.. math::
   \DeclareMathOperator*{\argmin}{argmin}
   {\bf p}^\ast &= \argmin_{{\bf p} \in \mathbb{R}^n} \; c({\bf p}) \\
   \text{such that} \; 0 &\leq v({\bf p}) \leq V \\
                       0 &\leq p_i \leq 1, \; i = 1, \ldots n

Here is a corresponding conf.py:

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'LiDO'
copyright = '2023, Watts'
author = 'Watts'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = []

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']



# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']

latex_elements = {
'preamble': """\\DeclareMathOperator*{\\argmin}{argmin}
"""
}
Environment Information
Platform:              linux; (Linux-6.4.6-100.fc37.x86_64-x86_64-with-glibc2.36)
Python version:        3.10.10 (main, Jul  7 2023, 14:09:08) [Clang 15.0.7 (Fedora 15.0.7-2.fc37)])
Python implementation: CPython
Sphinx version:        7.0.0
Docutils version:      0.19
Jinja2 version:        3.1.2
Pygments version:      2.13.0
Sphinx extensions
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 
    'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.graphviz']
Additional context

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.