Are questions about Python-Sphinx documentation TeX markup off-topic?

Question

I recently asked this question: How to display an underscore literal in math mode?; It was voted off-topic.

Based on https://tex.stackexchange.com/questions/69421/how-can-i-render-mathematical-formulas-in-python-sphinx (particularly, it was migrated from StackOverflow to this site) and the mention of LaTeX in the Sphinx docs, I think it should not have been closed. However, I'm not sure and wanted to ask in meta to see what others think too.

In the meantime, I made a new question at StackOverflow if anyone is able to contribute to a solution: Sphinx LaTeX markup limitations.

Answer 1

I'd like to give another view of your question and why it got closed.

In my humble opinion, the question, as it is, doesn't provide enough information about what is being asked. I have the feeling that the error you reported is happening at the conversion time, rst -> <format>, and not the in the LaTeX -> PDF generation.

The error message clearly points at an error in the .rst file:

System Message: ERROR/3 (<fullpath>/AccrualsImplementor.rst, line 83)

You are right to think that either TeX or MathJaX (which implements a subset of TeX math stuff) will render your :math: element later on, but the parsing itself is failing, so it's not TeX fault. In this error level, it's a .rst syntax issue.

You are right in using \_ to display a literal underscore. That's the correct way of using it, including in Sphinx. I wrote the following .rst sample file:

Hello! :math:`a^2 + b^2 a\_b = c^2`.

.. math::

   (a + b)^2 = a^2 + 2ab + b^2

   (a - b)^2 = a^2 - 2ab a\_b + b^2

Then I tried to generate an HTML version:

$ make html
Running Sphinx v1.1.3
loading pickled environment... done
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] index

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index

writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in _build/html.

which gave me:

And then I generated the LaTeX output:

$ make latex
Running Sphinx v1.1.3
loading pickled environment... done
building [latex]: all documents
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
processing Test.tex... index
resolving references...
writing... done
copying TeX support files... done
build succeeded.

Build finished; the LaTeX files are in _build/latex.

The relevant part of the generated .tex file:

\begin{document}

\maketitle
\tableofcontents
\phantomsection\label{index::doc}
Hello! $a^2 + b^2 a\_b = c^2$.
\begin{gather}
\begin{split}(a + b)^2 = a^2 + 2ab + b^2\end{split}\notag\\\begin{split}(a - b)^2 = a^2 - 2ab a\_b + b^2\end{split}\notag
\end{gather}

\renewcommand{\indexname}{Index}
\printindex
\end{document}

After running pdflatex, I have:

So you see, the problem has to rely in your .rst file.

The second part would involve posting relevant part of your code for us to reproduce your error - a minimal example. This is highly recommended, so we can track down the offending code and help you solve it. Sadly, the question only had an error message, without either the .rst or .tex code, so little we could do. :(

And since the error was not TeX-related, the question was closed as off-topic.

Don't take the closing issue too seriously, this is a great community, and I'm sure we would solve the error if it was really TeX-based. Sadly, as it is, .rst is not our cup of tea. :(

Anyway, my advice is to take a look at your .rst, I'm sure it's a markup problem, or even an error that happened some lines before and got propagated to the math part. :)

Answer 2

This is a tricky issue because when other software interacts or generates TeX code, it's not always easy to decide whether the problem derives from the interaction (off topic) or TeX itself (on topic).

One way to tell the difference, is if your code will compile when made into a regular LaTeX document and compiled without use of the interface. If that's the case, the problem is most likely off topic.

Although even in that case there's no completely clear dividing line. For example, many R + LaTeX questions are routinely considered on-topic here provided they are not purely R questions.

Another problem is that it's often the case when people come to TeX via this sort of route, their questions are trivial if they read a good introduction to LaTeX, which many times they haven't. (I'm not saying that this is your case.)

In the case of the new question you linked to, I think it is still off topic, since it seems to depend a lot on how the interface to LaTeX is implemented, rather than the LaTeX code itself. The question itself also contains code fragments, which makes it very hard for anyone to play with; the fact that the code is not directly LaTeX code makes the question even more off topic.

Answer 3

I think that they are (and should be) off topic in general. Sphinx is, in this context, a generator of (La)TeX code. If it is generating bad code then that is a problem with the input to the generator (or the generator itself). In this respect it should be treated the same as questions about (say) a C or perl or ... program that makes LaTeX output. The site doesn't have the resources to answer questions about arbitrary programming languages that just happen to generate LaTeX.

I think in the case of Sphinx the situation is slightly obscured as the math input syntax looks latex-like, however as your question showed it is not latex and there are valid latex expressions that are not accepted by the system, so I think it is best to consider it a LaTeX generator and these, as a whole, are off topic.

Looking at the discussion on the Stack Overflow version of the question it highlights even more why it should be off topic. It appears that the TeX back end was not being used at all so that TeX was not involved and the error messages being reported were javascript errors from the old jsmath javascript library. jsmath (and its newer replacement mathjax) are also considered off topic. They parse a very restricted subset of LaTeX syntax but render it using css (or svg) and do not use TeX at all.