Does Latex beamer work with Sphinx?

[Christoph Buchner]

Hi!

I have just created a quickstart document using sphinx 1.6.2. Immediately after creating it, I ran `make latexpdf`, and this correctly creates a pdf.
Since I actually want to create slides from Sphinx rst, and since the docs suggest that this is possible, I  changed the documentclass argument from 'manual' to 'beamer'.
Unfortunately, after cleaning the build folder and rerunning `make latexpdf`, I am greeted with

(/usr/share/texlive/texmf-dist/tex/latex/titlesec/titlesec.sty

Package titlesec Warning: Non standard sectioning command detected
(titlesec)                Using default spacing and no format.


Package titlesec Warning: Non standard sectioning command detected
(titlesec)                Using default spacing and no format.


Package titlesec Warning: Non standard sectioning command detected
(titlesec)                Using default spacing and no format.

! Undefined control sequence.
<argument> \paragraph
                     
l.1289 \ttl@extract\paragraph

and I don't know how to fix this. I am using Ubuntu 16.04 and have installed Texlive 2015.20160320-1, afaik this was the default one that was in the repos.

Is this a known problem?
Can creating slides from rst this way actually work?

Thank you for any pointers!

Best,
Christoph

p.s.: I have also investigated other options, but the other main contender for my use case, hieroglyph, which is mentioned in the Sphinx FAQ, seems to be basically unmaintained.

[jfbu]

Le 25/07/2017 à 22:42, Christoph Buchner a écrit :
> documentclass argument from 'manual' to 'beamer'.

> ...

> Package titlesec Warning: Non standard sectioning command detected
> (titlesec) Using default spacing and no format.
>
> ! Undefined control sequence.
> <argument> \paragraph
>
> l.1289 \ttl@extract\paragraph
>
>

> ...

> Is this a known problem?

Hi,

beamer is incompatible with titlesec as this shows:

\documentclass{beamer}
%\let\paragraph\section
%\let\subparagraph\section
\usepackage{titlesec}

\begin{document}
hello
\end{document}

but de-commenting the two "\let" lines at least allows latex
to work on this.

Thus you could try in conf.py

latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',

'passoptionstopackages' : r'''
\let\paragraph\section
\let\subparagraph\section
''',
}

but then we get into another problem

! LaTeX Error: Command \definitions already defined.
Or name \end... illegal, see p.192 of the manual.


Indeed, sphinx.sty has a

\newenvironment{definitions}{...}{...}

This is Python legacy and there are other usage of common words
in commands and environments, although Sphinx is moving more and
more to using systematically a prefix "sphinx".

Sadly many packages and classes in LaTeX pay no attention
to such problems and consider normal to define commands or
environments with such names as "definition", "strong", "total",
etc... and LaTeX has no mechanism whatsoever against such
clashes (no module name spaces in LaTeX)

From Beamer doc

The beamer class predefines several environments, like theorem or definition or proof, that you can use to typeset things like, well, theorems, definitions, or proofs. The complete list is the following: theorem, corollary, definition, definitions, fact, example, and examples. The following German block environments are also predefined: Problem, Loesung, Definition, Satz, Beweis, Folgerung, Lemma, Fakt, Beispiel, and Beispiele.

Thus we are led to

'passoptionstopackages' : r'''
\let\paragraph\section
\let\subparagraph\section
\let\definitions\relax
\let\enddefinitions\relax
''',


with this make latexpdf completes on hello world document.

I am sure there will be many issues.

Already, in LaTeX there are many conflicts between packages.

But here we are talking about using Beamer class, which makes
drastic changes to all LaTeX document commands.

Thus it *might* work, and please report if it does ;-) !


Ultimate fixes can be obtained this way:

do once make latexpdf

copy over the sphinx.sty file from the build repertory and put
it at top level in your real project

then add in conf.py

latex_additional_files = [ 'sphinx.sty' ]

and customize as desired the sphinx.sty file, for example
removing all titlesec related things in this case, or removing
the "definitions" environment.

But the Sphinx LaTeX writer might want to use that environment
and Beamer has its own version so there will be clash.

To be complete you would need to examine the Sphinx LaTeX writer
latex.py file and modify all its LaTeX macros to use Beamer syntax
if needed...

> Can creating slides from rst this way actually work?

perhaps someone will tell us...

>
> Thank you for any pointers!
>
> Best,
> Christoph
>

> p.s.: I have also investigated other options, but the other main contender for my use case, hieroglyph <https://github.com/nyergler/hieroglyph>, which is mentioned in the Sphinx FAQ, seems to be basically unmaintained.
>

Best,
Jean-Francois

[jfbu]

Le 26/07/2017 à 08:55, jfbu a écrit :
> Thus we are led to
>
> 'passoptionstopackages' : r'''
> \let\paragraph\section
> \let\subparagraph\section
> \let\definitions\relax
> \let\enddefinitions\relax
> ''',
>
>
> with this make latexpdf completes on hello world document.
>
> I am sure there will be many issues.

I tried this with Sphinx own docs and there are issues
the first one is

! Undefined control sequence.
\FNH@spewnotes ...@gobbletwo \FNH@H@@footnotetext
{\unvbox \FNH@notes }\endg...
l.9256 \sphinxattableend\end{savenotes}

? R
OK, entering \nonstopmode...
[268] [269] [270] [271] [272] [273] [274] [275]


where I suspect a problem with hyperref+beamer as is confirmed a bit later on

! Undefined control sequence.
\capstart ->\ifcapstart \H@refstepcounter
\@captype \hyper@makecurrent \@cap...
l.10520 \capstart

! Undefined control sequence.
\capstart ...counter \@captype \hyper@makecurrent
\@captype \global \let \hc...
l.10520 \capstart

strangely there is then this error


! Package xcolor Error: Undefined color `OldLace'.


and then we reach

[829] [830] [831] [832] [833] [834] [835] [836] [837] [838] [839] [840]

! LaTeX Error: Environment theindex undefined.

and from then one hundreds of errors of the type

! LaTeX Error: Lonely \item--perhaps a missing list environment.


due to the missing theindex environment.

and LaTeX aborts.

But it has almost completed successfully (800 "pages" produced before catastrophic failure at the time of typesetting the indices)

Thus it should be possible perhaps with enough hacking around to make it work,
Ah I see in the log file

Package footnotehyper-sphinx Warning: Footnotes will be sub-optimal, sorry. Thi
s is due to the document class or
some package modifying macro \@makefntext.
You can try to report this incompatibility at
https://github.com/sphinx-doc/sphinx with this info:.

macro:#1->\def \insertfootnotetext {#1}\def \insertfootnotemark {\@makefnmark }
\usebeamertemplate ***{footnote}


So here we need footnotehyper-sphinx to contain a special detection routine of beamer class. The message only says footnote will be "sub-optimal" and at this stage I don't know if this problem with \@makefntext explains the error reported above with \FNH@H@@footnotetext

I will ping the author of footnotehyper.

I am a bit more worried about the

----
! Undefined control sequence.
\capstart ->\ifcapstart \H@refstepcounter
\@captype \hyper@makecurrent \@cap...
l.10520 \capstart

The control sequence at the end of the top line
of your error message was never \def'ed. If you have
----

Because investigating Hyperref issues is very demanding.

I can't investigate at all now, perhaps a bit later today but I am short on time.
And may not be able to return to this until a few weeks

Thus, currently it is not possible to use Beamer class.

Best,

Jean-Francois

[Christoph Buchner]

Dear Jean-Francois,

thank you very much for the very thorough investigation! The confusing nature of the error output remind me of my past (thesis) day when I was fighting with Latex. :D

I think for the moment I won't try to convince Sphinx of my intentions, and will try to make either https://github.com/myint/rst2beamer work ("A docutils script converting reStructuredText into Beamer-flavoured LaTeX."), or try to find willing maintainers to fix bugs in https://github.com/nyergler/hieroglyph/ (it is "recommended"/mentioned in the sphinx faq, after all).

All the best,
Christoph

[jfbu]

Le 26/07/2017 à 20:09, Christoph Buchner a écrit :
>
>
> On Wednesday, 26 July 2017 09:30:24 UTC+2, jfbu wrote:
>>

>> ...

>> ! Undefined control sequence.
>> \FNH@spewnotes ...@gobbletwo \FNH@H@@footnotetext

>> ...

>> ! Undefined control sequence.
>> \capstart ->\ifcapstart \H@refstepcounter
>> \@captype \hyper@makecurrent \@cap...
>> l.10520 \capstart
>>
>> ! Undefined control sequence.
>> \capstart ...counter \@captype \hyper@makecurrent
>> \@captype \global \let \hc...
>> l.10520 \capstart
>>

>> ...

>> ! Package xcolor Error: Undefined color `OldLace'.
>>
>>
>> and then we reach
>>
>> [829] [830] [831] [832] [833] [834] [835] [836] [837] [838] [839] [840]
>>
>> ! LaTeX Error: Environment theindex undefined.
>>
>
>

> Dear Jean-Francois,
>
> thank you very much for the very thorough investigation! The confusing nature of the error output remind me of my past (thesis) day when I was fighting with Latex. :D
>

Dear Christoph

I looked a bit more and it appears the Beamer class loads the
hyperref package in such a context that hyperref loading is only
partial. As a result, a number of hyperref macros are left
undefined. This explains most of the errors above, including
the first one with \FNH@H@@footnotetext, because that macro
is made an alias to the undefined \H@@footnotetext. But the
package footnotehyper-sphinx is fooled by the fact that the
Boolean \ifHy@hyperfootnotes is actually defined with value
\iftrue, despite hyper-footnotes related macros not being
defined as expected from package hyperref.

The error with undefined color is due to the fact that
xcolor is already loaded by Beamer class and the subsequent
loading by Sphinx is ignored (and the conf.py was configured
to pass some option to xcolor so that it would know OldLace).

Similarly hyperref options declared by Sphinx would be ignored
because they use \PassOptionsToPackage, but hyperref has
already been loaded by Beamer so it is too late.

(and it has been loaded in strange way, which causes hyperref
to say in the log "it was stopped early")

All of these issues could be solved by a determined LaTeX user
having the time.

There remains the one of missing environment "theindex". Here
also it can be solved by defining it oneself.

So with some work one can for example compile the Sphinx own
docs as a Beamer presentation (of about 900 slides...)

This will have the design of a Beamer presentation but
the source is lacking all of the specific Beamer commands.

It would make more sense possibly then to use rather
\usepackage{beamerarticle} in the preamble (I have forgotten
what happened when I tried[1], some of the issues above
were still there) rather than setting the document class
to beamer.

[1] ah yes, there was also an error due to option clash for
package color if I remember correctly

Anyway, if you really want to make a Beamer presentation
you need a Beamer writer on Sphinx side, not a LaTeX writer.

Because you want to be able to use all commands specific
to a Beamer presentation.

But the Sphinx LaTeX style file is tested and done for the
standard classes, as is the case of all the packages it
uses. It is rather surprising actually that apart from
the titlesec incompatibility (for which I indicated a workaround)
and the hyperref peculiarities and the issues with package
options (xcolor for example), it turns out to be almost possible
to use the Sphinx LaTeX writer output directly with beamer class.

> I think for the moment I won't try to convince Sphinx of my intentions, and will try to make either https://github.com/myint/rst2beamer work ("A docutils script converting reStructuredText into Beamer-flavoured LaTeX."), or try to find willing maintainers to fix bugs in https://github.com/nyergler/hieroglyph/ (it is "recommended"/mentioned in the sphinx faq, after all).
>

Certainly an "rst2beamer" is better but I don't know how
that can be made to fit with auto-documenting Python code
for example; how could one use say autodoc: where will
it pause?
how will it split Python code documentation into frames ?
Or, would the docstrings contain the Beamer specific
syntax ?

Best,

Jean-Francois


> All the best,
> Christoph
>

[Christoph Buchner]

 
I don't know about autodoc, I'm sure not all features are appropriate for a presentation.
Other markup-to-presentation tools typically handle slide separations based on the section structure of the document (e.g. top-level is presentation title, next level presentation sections, next level slides), with the possibility to also use a REst transition (4+ punctuation marks) as a slide separator, with an empty slide title, or the title of the previous slide.

[Olle Hynen]

Reviving this old thread: if you feel like it, please try out https://pypi.org/project/sphinxcontrib-beamer/ which I recently developed for my own use.