search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.52k stars 2.12k forks source link

Latex output "too deeply nested" #777

Closed shimizukawa closed 8 years ago

shimizukawa commented 9 years ago

If Sphinx's LaTeX output gets too deeply-nested, I get the following error:

[13] [14]
Chapter 4.
[15]

! LaTeX Error: Too deeply nested.

I've found an item on the Docutils to-do list: http://docutils.sourceforge.net/docs/dev/todo.html indicating that this is something they're aware of, but have not yet fixed, but I'm wondering if this is something Sphinx can work around in the mean time.

In particular, the LaTeX "enumitem" package: http://www.tex.ac.uk/CTAN/macros/latex/contrib/enumitem/ has recently added support for list environments of any depth. I was wondering if Sphinx could make use of this package to allow nesting of chapters and code blocks to a higher number of levels, because when you start using code blocks with several levels of indentation, the nesting gets deep quickly, and standard LaTeX maxes out somewhere around 5-6 levels.

Could something like this work?

shimizukawa commented 9 years ago

From Anonymous on 2011-12-29 08:26:07+00:00

You will find really 100s of exercises available that will help you gain muscles and this can be done by doing bench presses, dead lifts or by utilizing hand weights. These workouts are the very best if this involves firming and strengthening the muscles. nfl shop http://www.nfl-shops.com/ Cheap NFL Jerseys http://www.nfl-shops.com/ NFL Jerseys http://www.nfl-shops.com/ nfl shop jerseys http://www.nfl-shops.com/ http://www.nfl-shops.com/san-francisco-49ers-jerseys-c-76.html

shimizukawa commented 9 years ago

From kaiwa on 2012-07-18 12:31:15+00:00

+1 for using enumitem package

shimizukawa commented 9 years ago

From Martin Ortbauer on 2012-09-05 12:36:10+00:00

I encountered the same problem. did you or somebody already implement that? or did you find some workaround? thanks

shimizukawa commented 9 years ago

From tonycpsu on 2012-09-05 14:49:20+00:00

I don't know of any workarounds other than lowering the number of nesting levels in my documents. I would love it if Sphinx could switch to using enumitem to get rid of this limit.

shimizukawa commented 9 years ago

From Nicolas M. Thiéry on 2013-08-29 15:12:46+00:00

+1 to using enumitem as well. We stumbled on this problem in Sage [1]:

Probably a bit more work will actually be needed, for there seems to be a bug in the \@listdepth incrementation/decrementation with Sphinx+enumitem: for a file which is not soo deeply nested (10 maybe?) but quite long, we actually need to use \setlistdepth{264} !

Cheers, Nicolas

[1] http://trac.sagemath.org/ticket/9107#comment:42

shimizukawa commented 9 years ago

From Nicolas M. Thiéry on 2014-06-13 08:36:59+00:00

I got annoyed because we now need to use \setlistdepth{2000}, so the problem was just going to become worst and worst with time. So I investigated a bit further, and found out that if we replace list by trivlist in the customized Verbatim defined by sphinx.sty, then our documenation compiles smoothly, without even using enumitem.

To everyone here: does this fix your own compilation errors?

To the sphinx devs: does this seem like a sensible change to do to sphinx.sty?

shimizukawa commented 9 years ago

From Nicolas M. Thiéry on 2014-06-13 09:16:52+00:00

I proposed a pull request for this on: https://bitbucket.org/birkenfeld/sphinx/pull-request/250/

nthiery commented 9 years ago

Ping? Does using trivlist sound reasonable?

kiwifb commented 8 years ago

Resurrecting the discussion. Using trivlist sounds ok to me. Looking at the doc that would also means that some of the lengths are set to 0 automatically so a few (but not all) \setlength statements could be removed.

jfbu commented 8 years ago

yes using trivlist is definitely feasible, avoids the check for nesting depth done by list and if needed (I have not looked closerly) we can always add some of the things done by list and not by trivlist either at begin or end. I can work on this tomorrow.

jfbu commented 8 years ago

Initially I thought from comment by @kiwifb the issue was with Verbatim, and I self-assigned to me. I fixed that but this only spares one level of nesting. Reading the whole thread I realized the issue was more general, related to lists. The package enumitem was mentioned, but the simplest would be to remove from LaTeX's \list code the check for depth. Then the above commit would be unneeded. Anyway, @kiwifb can you tell me if PR #2624 solves your issue ?

kiwifb commented 8 years ago

No luck. I am doing a serial build to disentangle things and give you a clean output, that will take a little while.

kiwifb commented 8 years ago 
Underfull \hbox (badness 10000) in paragraph at lines 6122--6124
[]\T1/ptm/m/n/10 A first ap-proach is to pass the \T1/pcr/m/n/10 roots \T1/ptm/
m/n/10 and \T1/pcr/m/n/10 children \T1/ptm/m/n/10 func-tions as ar-gu-ments to
[77]

LaTeX Warning: Hyper reference `sage/combinat/backtrack:sage.combinat.backtrack
.SearchForest' on page 78 undefined on input line 6182.

! Missing \endcsname inserted.
<to be read again> 
                   \let 
l.6186 \begin{Verbatim}[commandchars=\\\{\}]

? 
! Emergency stop.
<to be read again> 
                   \let 
l.6186 \begin{Verbatim}[commandchars=\\\{\}]

!  ==> Fatal error occurred, no output PDF file produced!
Transcript written on combinat.log.

I can provide the log if necessary or any other files you may need.

jfbu commented 8 years ago

Thank you for trying PR #2624. Your project has no issue with make latexpdf on 1.4.3?

jfbu commented 8 years ago

well, my question was silly because you surely have earlier reported "too deeply nested". But perhaps there were other issues than the "too deeply nested" one. I don't see how Missing \endcsname inserted can arise from PR #2624, but I will think if I get time.

kiwifb commented 8 years ago

Actually I probably should run a check with pure 1.4.3. That issue as been going on for a long time and I don't know how many people did try runs apart from me at this stage.

kiwifb commented 8 years ago

Well that's interesting same error. 


! Missing \endcsname inserted.
<to be read again> 
                   \let 
l.448 \begin{Verbatim}[commandchars=\\\{\}]

? 
! Emergency stop.
<to be read again> 
                   \let 
l.448 \begin{Verbatim}[commandchars=\\\{\}]

So we have moved from the nesting issue. Going with trivlist in sphinx 1.4.1 got things build. Checking with 1.4.3.

kiwifb commented 8 years ago

Same error when replacing list by trivlist in 1.4.3 so it must be something new.

jfbu commented 8 years ago

Thank you for reporting.

jnothman commented 8 years ago

Getting the same \endcsname and Verbatim issue as @kiwifb trying to build scikit-learn user guide with latexpdf in sphinx 1.4.2 and 1.4.3. I suspect this isn't the small project you're looking for :/

However, the error occurs with Verbatim in a notice environment or a SphinxShadowBox, and goes away when that environment is removed, so it may be simple for you to produce a minimal failing example.

Error context:

! Missing \endcsname inserted.
<to be read again>
                   \let
\@ifnextchar #1#2#3->\let
                          \reserved@d =#1\def \reserved@a {#2}\def \reserved...

\@ifundefined #1->\expandafter \ifx \csname #1
                                              \endcsname \relax \expandafter...

\begin #1->\@ifundefined {#1}
                             {\def \reserved@a {\@latex@error {Environment #...

\\Verbatim ...framed \noindent \begin {\minipage }
                                                  {\linewidth }\fi \MakeFram...
l.226 \begin{Verbatim}[commandchars=\\\{\}]
jfbu commented 8 years ago

ah! sorry to everyone. This should be \begin{minipage} not \begin{\minipage}. This is only a typo, but obviously with big consequences :-(( very sorry about this. I will correct very soon on stable branch.

jfbu commented 8 years ago

I have fixed the sub-issue reported by @jnothman and @kiwifb at d4a9997 (on stable branch). With apologies, bad commit was 68becb1. I will merge the fix also into PR #2624 which is mentioned in the current thread.

jfbu commented 8 years ago

@jnothman @kiwifb sadly there is another issue besides the typo with code-blocks inside warning admonitions. Reported at #2640. Will work on it (it's all my fault as I committed the new code for warning admonitions).

jfbu commented 8 years ago

I have fixed the extra LaTeX issue at PR #2641. It was again related to the minipage thing but in a subtle way. Rather than \begin{minipage}/\end{minipage}, the code should have used \minipage/\endminipage due to some idiosyncrasy of original Verbatim environment. I have fixed it a slightly different way. @jnothman, @kiwifb, is this is better for you ? (I have merged the fix into PR #2624 which does the trivlist thing).

kiwifb commented 8 years ago

I will give it a try soonish. Sorry for not being more responsive, as with jnothman, sage is not the small project you are looking for.

kiwifb commented 8 years ago

No improvements, same message when applying the new PR #2624.

LaTeX Warning: Hyper reference `sage/rings/asymptotic/growth_group::doc' on pag
e 8 undefined on input line 438.

! Missing \endcsname inserted.
<to be read again> 
                   \let 
l.448 \begin{Verbatim}[commandchars=\\\{\}]

? 
! Emergency stop.
<to be read again> 
                   \let 
l.448 \begin{Verbatim}[commandchars=\\\{\}]
jfbu commented 8 years ago

@kiwifb thanks for trying, and sorry to hear it fails. This is same error as before, are you sure the \begin{\minipage} is correctly replaced by \begin{minipage} in new sphinx.sty ? I can't until tomorrow afternoon, but if I get time by then I will try to see if I can clone the sage repo or sage doc repo and see for myself. (I hope my laptop has enough disk space ;-) )

kiwifb commented 8 years ago

It is not. It is very bizarre when I look at #2624 I did wget https://github.com/sphinx-doc/sphinx/pull/2624.patch and I got the individual commits from that, and in the first commit I got 

-  \relax\ifSphinx@inframed\noindent\begin{\minipage}{\linewidth}\fi
+     \ifSphinx@inframed\noindent\begin{\minipage}{\linewidth}\fi

so no replacement. When I look at file changed on the same PR I see:

-  \relax\ifSphinx@inframed\noindent\begin{minipage}{\linewidth}\fi
+     \ifSphinx@inframed\noindent\begin{minipage}{\linewidth}\fi

So I am guessing the change from \minipage to minipage is something I didn't catch by just patching with the commits. I see the change came with the merge but somehow it got missing in the patch. Trying again.

jfbu commented 8 years ago

Perhaps I made it complicated for you getting a correct patch as I merged stable multiple times into this topic branch. Simplest would be if you git clone https://github.com/jfbu/sphinx.git and checkout its latex_avoidtoodeeplynested branch. In the Makefile of your project you can then set SPHINXBUILD = /path/to/clone/sphinx/sphinx-build.py.

(I should have rebased my topic branch on stable; as stable got some critical fixes, I couldn't leave the PR on top of 1.4.3, and I chose to merge stable into it. Next time I shall rebase.)

kiwifb commented 8 years ago

I just made the small minipage change for now. sage is unfortunately a complicated beast and I wouldn't recommend you to try to build it and its documentation for debugging sphinx unless you are an experienced sage developer.

As it is, I am the developer of sage-on-gentoo so it is a bit easier for me to pull this kind of things but I still install a patched sphinx as my system wide one for this. If the small change fails, I'll pull your branch - I can package that, no problems.

kiwifb commented 8 years ago

OK different error but after what you say I'd better test out your branch

[82[functions] /scratch2/portage/sci-mathematics/sage-9999/work/sage-9999/src-python2_7/doc/en/reference/functions/sage/functions/hyperbolic.rst:: WARNING: unusable reference target found: ../../../../../../html/en/reference/calculus/sage/symbolic/function.html#sage.symbolic.function.GinacFunction
]]

! LaTeX Error: Something's wrong--perhaps a missing \item.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...                                              

l.7205 \end{notice}

? 
! Emergency stop.
 ...                                              

l.7205 \end{notice}

!  ==> Fatal error occurred, no output PDF file produced!
jfbu commented 8 years ago

If you have a clone of sphinx-doc you can add this at bottom of .git/config file

[remote "jfbu"]
    url = https://github.com/jfbu/sphinx.git
    fetch = +refs/heads/*:refs/remotes/jfbu/*

and then [edit] git fetch jfbu, git checkout jfbu/latex_avoidtoodeeplynested could possibly work (I am no git expert). 

git fetch jfbu latex_avoidtoodeeplynested:latex_avoidtoodeeplynested

followed by git checkout latex_avoidtoodeeplynestedshould do it

jfbu commented 8 years ago

The kind of latest error you get may be among the things recently fixed in sphinx-doc stable branch.

kiwifb commented 8 years ago

OK, I need to do some other stuff but I'll try ASAP. I can package a git branch in Gentoo that is not an issue but thanks for the advice (which is almost correct but not quite I think).

kiwifb commented 8 years ago

Pulled your repo, switched to the branch, build, install. Rebuilding sage's documentation:

LaTeX Warning: Hyper reference `sage/game_theory/normal_form_game:nn2007' on pa
ge 21 undefined on input line 1717.

Runaway argument?
\\ 
! Paragraph ended before \align* was complete.
<to be read again> 
                   \par 
l.1734 

? 
! Emergency stop.
<to be read again> 
                   \par 
l.1734 

!  ==> Fatal error occurred, no output PDF file produced!

new error...

jnothman commented 8 years ago

new error...

us too: yours looks like it could be another instance of #2646

kiwifb commented 8 years ago

Yes looks like it. I'll join the discussion over there to get updates.

jfbu commented 8 years ago

@kiwifb I rebased the underlying topic branch on my repo for PR #2624 onto latest stable. This in order to create safer diff patch. But you will need -f for next fetch. Sorry about this ... I hope your build will succeed soon !

kiwifb commented 8 years ago

It succeeded with your branch and the the fix associated with #2646. The rebasing will make it easier to package it for other people to use it though.

jnothman commented 8 years ago

Thank you! the current stable branch is compiling scikit-learn's documentation again.

On 9 June 2016 at 18:22, François Bissey notifications@github.com wrote:

It succeeded with your branch and the the fix associated with #2646 https://github.com/sphinx-doc/sphinx/issues/2646. The rebasing will make it easier to package it for other people to use it though.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/sphinx-doc/sphinx/issues/777#issuecomment-224830256, or mute the thread https://github.com/notifications/unsubscribe/AAEz62oTBL0gOOa26mBDvKs6n7osFVmoks5qJ81SgaJpZM4DN5yb .

jfbu commented 8 years ago

@kiwifb @jnothman big relief ...

jfbu commented 8 years ago

Reopening because b2be594 only addresses partially the issue. Together with PR #2651 when it will be merged, the situation with code-blocks will be that they are allowed at maximal nesting depth within lists/quotes. With latex defaults if no list package is loaded, this is 6 levels of nesting.

Memo: by default latex allows 4 levels of enumerated lists, 4 levels of labeled lists, and 6 levels total of lists, inclusive of quotes, which also are a list in disguise in latex. Prior to b2be594 code-blocks however could happen only at max depth 4. Now 5, and PR #2651 will make this six. edit now merged into stable at 7fd7d29. Thus now code-blocks will be allowed at maximal depth from document class+list packages.

But this does not lift the "4" max levels of either enumerated or labeled lists.

jfbu commented 8 years ago

I am reopening for the same reason. 4a0b283 only fixes to the extent that code-blocks are now allowed at deepest level, but nothing is changed to LaTeX defaults regarding max nesting of lists and quotes.

mindw commented 8 years ago

got hit by this issue while building sqlalchemy PDF doc. The following worked for me:

\usepackage{enumitem}
\setlistdepth{20}
\renewlist{itemize}{itemize}{20}

% initially, use dots for all levels
\setlist[itemize]{label=$\cdot$}
\setlist[itemize]{labelsep=.5em}

% customize the first 3 levels
\setlist[itemize,1]{label=\textbullet}
\setlist[itemize,2]{label=--}
\setlist[itemize,3]{label=*}
jfbu commented 8 years ago

@mindw

Thanks for the tip. Loading enumitem and using \setlistdepth allows to ease up the cap on maximal depths, but one must also, as you do in your code, \renewlist explicitely the itemize, enumerate and description to reset the cap on listdepth for them.

I wanted to test this and I have an issue, I can't get it to work:

\documentclass{article}

\usepackage{enumitem}
\setlistdepth{10}
\renewlist{itemize}{itemize}{10}
\setlist[itemize]{label=$\cdot$}
\setlist[itemize]{labelsep=.5em}

\setlist[itemize,1]{label=\textbullet}
\setlist[itemize,2]{label=--}
\setlist[itemize,3]{label=*}
\setlist[itemize,4]{label=*}

\begin{document}

%does NOT work! Package enumitem Error: Undefined label. (at level of \item e)

\begin{itemize}
\item a
  \begin{itemize}
  \item b
    \begin{itemize}
    \item c
      \begin{itemize}
      \item d
        \begin{itemize}
        \item e
          \begin{itemize}
          \item f
          \end{itemize}
        \end{itemize}
      \end{itemize}
    \end{itemize}
  \end{itemize}
\end{itemize}
\end{document}

Does your document really have 5 or more nested itemize ? or is it simply the maximal nesting depth which goes beyond 6 and is fixed by your set-up ?

This is with enumitem 2011/09/28 v3.5.2. Could you also check in your latex log the version you use (in case my code snippet above does work with your version of enumitem).

jfbu commented 8 years ago

@mindw

I see your code snippet also here. However notice that the accepted answer explicitely sets the label at each level (in the case of enumerate). I checked the enumitem manual and the fact that my code snippet is not working does seem to contradict the manual. This is possibly a bug in package enumitem, or in its documentation. This problem complicates incorporating use of enumitem into Sphinx (additionally to the fact that we should not break people's setup which already use it). Besides enumitem has had some updates after TL2009 which Sphinx currently supports. It appears some of these updates precisely refers to issues with \setlist.

Memo:

jfbu commented 8 years ago

@mindw

I got it just before posting a bug report to enumitem's author !

Your code should be with

\setlist[itemize]{label=$\cdot$, labelsep=.5em}

and not with

\setlist[itemize]{label=$\cdot$}
\setlist[itemize]{labelsep=.5em}

It appears that the second use of \setlist upsets the first one. I have no idea if this is clear from the enumitem doc. But this does complicate matters for incorporating use of enumuitem in Sphinx.

jfbu commented 8 years ago

PR #3096 addresses this without resorting to package enumitem. Of course enumitem has much to recommend it, but its version in TeXLive 2009 which Sphinx supports was at 2.x, and later it reached 3.5.2, with some important changes. Once Sphinx will support only TeXLive 2013 or later, we can more easily consider using enumitem which had no changes since.