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

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.

• Oct 23, 2012 at 13:56

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
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. :)

• This doesn't explain why it says that \textunderscore and \textrm and \biggl or \biggr are invalid LaTeX commands. Also, as soon as I removed the underscores, everything else compiled with the docs without a problem. So I'm not buying this.
– user12413
Oct 23, 2012 at 13:48
• However, I do totally agree with your reasoning for why it was closed as off-topic. I'm more interested in whether Sphinx-LaTeX questions are generally off-topic. I understand it in the case of my specific question.
– user12413
Oct 23, 2012 at 13:49
• @EMS: I'm lost here, apologies for not being a Sphinx user. :) In which part of the "process" do you get those messages about \textunderscore and friends? Oct 23, 2012 at 13:55
• Check the link to the StackOverflow version of my question. When I build the documentation (e.g. invoke Sphinx's conversion to and subsequent use of TeX), I see those errors.
– user12413
Oct 23, 2012 at 16:01
• @EMS: IMHO, I think your gather environment is the one to blame. If I remove the & right after &=, everything works fine. Oct 23, 2012 at 16:33
• Could it be a Sphinx version issue? That does not fix it for me. What version are you using? I am using: 1.1.2-1.
– user12413
Oct 23, 2012 at 17:00
• N/M, I see that it is 1.1.3 in the answer above. Perhaps this is it.
– user12413
Oct 23, 2012 at 17:01
• The answer, incidentally, has to do with symbols that jsMath does not recognize. The problem did not occur in the .rst file as you suggest. It was simply a matter of why TeX symbols are valid. While I agree my original question should be marked off-topic, I think Sphinx more broadly is definitely on-topic at this site. You are also mistaken about the TeX-to-PDF comment. There is no TeX to PDF step in my question, since it is doc being built for a website. And also, Sphinx does indeed use the TeX program directly. It was just jsMath which does not allow some symbols.
– user12413
Oct 26, 2012 at 21:40

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.

• I don't understand the last few sentences. Is it the case that a question must only consist of TeX code for it to be on-topic? There are many markup languages where you express correct syntax differently than it would look in a plain TeX document, but it can be important to ask "why isn't this markup making the right thing." If the answer is, "because the markup library is wrong" then I can see it being off-topic. But if you specify the markup correctly, and the markup describes correct TeX code, but you just expressed the wrong TeX code, that would seem to be overwhelmingly on-topic.
– user12413
Oct 22, 2012 at 19:36
• @EMS I agree with the last point, but then put the relevant TeX code into a minimal working TeX document and ask the question that way. Then there's no need to complicate the issue with a non-TeX markup system. Oct 22, 2012 at 19:38
• Also, even if many community members don't care to learn Sphinx, or other markup environments, it doesn't mean the questions are clutter. In my case, I'd be happy if everyone ignored my question save for the small fraction who use Python and know Sphinx. There ought to be some forum for asking questions like that, and this seems as good as any. Also, I don't like the distinction about 'trivial' questions. That same reasoning applies to beginners whether they came to TeX via a markup language or not. The whole 'what have you tried' thing...
– user12413
Oct 22, 2012 at 19:39
• But the question might be about why the markup doesn't cause the expected TeX output. It's not about whether the markup engine is good or not, nor whether the syntax is correct or not. For example, in the Sphinx case, a user might forget the '\\' after each equation line for an array, or the & fr alignment. I don't see why they should have to translate their code to TeX first to get help on something like that. What they have is a very good minimal working example, for anyone out there who knows basic Sphinx. And it's fine to ask targeting only those responders, imo.
– user12413
Oct 22, 2012 at 19:41

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.

• They aren't off-topic in general, given the link in my question above showing one that was successfully migrated from StackOverflow to this site. Also, if you follow the link to my question that's currently up at StackOverflow, one of the moderators (at both sites) suggested in the comments that it might be more appropriate here instead of there. (FWIW, I think my question probably is off-topic at this site, but many Sphinx questions would not be). Anyway, the question of whether they should be off topic is still open.
– user12413
Oct 25, 2012 at 18:07
• Also, the solution to my question ended up being a problem with which TeX symbols are allowable in jsMath vs. mathjax. In my view, this is exactly the right community to ask about that sort of thing.
– user12413
Oct 25, 2012 at 18:08
• Also, just to clarify, Sphinx directly uses AMSMath TeX. It doesn't generate something else. It does use unusual TeX code, but it's still TeX code. You seem to think that Sphinx is a different markup language that eventually produces TeX. That's not quite accurate. Inside of the math modes in Sphinx you are literally writing TeX code. The fact that a TeX command was invalid was an error on the part of jsMath, not Sphinx. And this meta question is about whether Sphinx is off-topic, not jsMath or mathjax.
– user12413
Oct 25, 2012 at 18:11
• Yes I see that but if you put valid tex markup into the document and you get an error then either sphinx has generated bad tex elsewhere in the document in the conversion from restructured text, or (as in your case) TeX isn't being used at all. In either of these cases the question is clearly off topic for a TeX forum. (MathJax has specifically been considered off topic (there is a separate question here on meta discussing that) Oct 25, 2012 at 18:22
• TeX is being used in my case. Just not all symbols. The same error could happen in a regular TeX editor writing plain old TeX. Say I was trying to use some symbol from a package, but my environment failed to include the right package. It's not much different here. And in both cases, I would seek a community of people who were familiar with the differences in the packages for help.
– user12413
Oct 25, 2012 at 18:30
• No, jsmath does not use TeX. It is a javascript program that parses a tex-like syntax. Oct 25, 2012 at 18:38
• From the Sphinx documentation: "The input language for mathematics is LaTeX markup. This is the de-facto standard for plain-text math notation and has the added advantage that no further translation is necessary when building LaTeX output." And futher: "This extension renders math via LaTeX and dvipng into PNG images. This of course means that the computer where the docs are built must have both programs available."
– user12413
Oct 25, 2012 at 18:42
• You can also configure it to use jsMath or MathJax if you wish, but that's not Sphinx's baseline functionality. And its syntax is LaTeX syntax, not some variant. In my case, our common work system is setup to use jsMath, so my question (as I already admitted many times) would have been off-topic. But most like mine would not be.
– user12413
Oct 25, 2012 at 18:43
• If you are generating png then my understanding is that it uses Tex, but that you were using a back end going to web pages not using images but using jsmath that does not use tex. Oct 25, 2012 at 18:44
• But that doesn't seem to affect the standing for general Sphinx/LaTeX questions. Just my singular question, for a very special reason. So I don't follow your generalization that my question could illustrate why general Sphinx/LaTeX questions should always be off-topic.
– user12413
Oct 25, 2012 at 18:46
• If you are using the tex back-end then it make sense to ask the question here using the generated file that sphinx actually sends to latex (so sphinx doesn't need to be in the question) Oct 25, 2012 at 18:46
• Oct 25, 2012 at 18:47