Merge pull request #2297 from jfbu/literalblockcaption

LaTeX captions of literal blocks now glued to framed verbatim

sphinx/texinputs/sphinx.sty

@@ -158,22 +158,96 @@
 \let\endOriginalVerbatim=\endVerbatim
 
 % Play with vspace to be able to keep the indentation.
-\newlength\distancetoright
+\newlength\Sphinx@scratchlength
-\def\mycolorbox#1{%
+\newcommand\Sphinxcolorbox [1]{%
-  \setlength\distancetoright{\linewidth}%
+  \setlength\Sphinx@scratchlength{\linewidth}%
-  \advance\distancetoright -\@totalleftmargin %
+  \advance\Sphinx@scratchlength -\@totalleftmargin %
   \fcolorbox{VerbatimBorderColor}{VerbatimColor}{%
-  \begin{minipage}{\distancetoright}%
+  \begin{minipage}{\Sphinx@scratchlength}%
     #1
   \end{minipage}%
   }%
 }
-\def\FrameCommand{\mycolorbox}
+% used for split frames for continuation on next and final page
+\def\MidFrameCommand{\Sphinxcolorbox}
+\let\LastFrameCommand\MidFrameCommand
+
+% We customize \FrameCommand (for non split frames) and \FirstFrameCommand
+% (split frames), in order for the framed environment to insert a Title above
+% the frame, which can not be separated by a pagebreak.
+
+% The title is specified from outside as macro \SphinxVerbatimTitle.
+% \SphinxVerbatimTitle is reset to empty after each use of Verbatim environment.
+
+% It is also possible to use directly framed environment (i.e. not indirectly
+% via the Verbatim environment next), then it is \SphinxFrameTitle which specifies
+% the title.
+\newcommand*\SphinxFrameTitle {}
+\newcommand*\SphinxVerbatimTitle {}
+\newcommand*\SphinxSetupCaptionForVerbatim [2]
+{%
+    \def\SphinxVerbatimTitle{\captionof{#1}{#2}\smallskip }%
+}
+
+% \SphinxCustomFBox is copied from framed.sty's \CustomFBox, but
+% #1=title/caption is to be set _above_ the top rule, not _below_
+% #1 must be "vertical material", it may be left empty.
+
+% The amsmath patches \stepcounter to inhibit stepping under
+% \firstchoice@false. We use it because framed.sty typesets multiple
+% times its contents.
+\newif\ifSphinx@myfirstframedpass
+
+\long\def\SphinxCustomFBox#1#2#3#4#5#6#7{%
+  % we set up amsmath (amstext.sty) conditional to inhibit counter stepping
+  % except in first pass
+  \ifSphinx@myfirstframedpass\firstchoice@true
+                  \else\firstchoice@false\fi
+  \leavevmode\begingroup
+  \setbox\@tempboxa\hbox{%
+    \color@begingroup
+      \kern\fboxsep{#7}\kern\fboxsep
+    \color@endgroup}%
+  \hbox{%
+    \lower\dimexpr#4+\fboxsep+\dp\@tempboxa\hbox{%
+      \vbox{%
+        #1% TITLE
+        \hrule\@height#3\relax
+        \hbox{%
+          \vrule\@width#5\relax
+          \vbox{%
+            \vskip\fboxsep
+            \copy\@tempboxa
+            \vskip\fboxsep}%
+          \vrule\@width#6\relax}%
+        #2%
+        \hrule\@height#4\relax}%
+    }%
+  }%
+  \endgroup
+  \global\Sphinx@myfirstframedpassfalse
+}
+
+% for non split frames:
+\def\FrameCommand{%
+   % this is inspired from framed.sty v 0.96 2011/10/22 lines 185--190
+   % \fcolorbox (see \Sphinxcolorbox above) from color.sty uses \fbox.
+   \def\fbox{\SphinxCustomFBox{\SphinxFrameTitle}{}%
+                 \fboxrule\fboxrule\fboxrule\fboxrule}%
+   % \fcolorbox from xcolor.sty may use rather \XC@fbox.
+   \let\XC@fbox\fbox
+   \Sphinxcolorbox
+}
+% for first portion of split frames:
+\let\FirstFrameCommand\FrameCommand
 
 \renewcommand{\Verbatim}[1][1]{%
   % list starts new par, but we don't want it to be set apart vertically
-  \bgroup\parskip=0pt%
+  \bgroup\parskip\z@skip
-  \smallskip%
+  \smallskip
+  % use customized framed environment
+  \let\SphinxFrameTitle\SphinxVerbatimTitle
+  \global\Sphinx@myfirstframedpasstrue
   % The list environement is needed to control perfectly the vertical
   % space.
   \list{}{%
@@ -184,15 +258,17 @@
   \setlength\leftmargin{0pt}%
   }%
   \item\MakeFramed {\FrameRestore}%
-     \small%
+     \small
     \OriginalVerbatim[#1]%
 }
 \renewcommand{\endVerbatim}{%
-    \endOriginalVerbatim%
+  \endOriginalVerbatim
-  \endMakeFramed%
+  \endMakeFramed
-  \endlist%
+  \endlist
-  % close group to restore \parskip
+  % close group to restore \parskip (and \SphinxFrameTitle)
-  \egroup%
+  \egroup
+  % reset to empty \SphinxVerbatimTitle
+  \global\let\SphinxVerbatimTitle\empty
 }
 
 

sphinx/writers/latex.py

@@ -1434,8 +1434,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.in_caption += 1
         if self.in_container_literal_block:
             self.body.append('\\needspace{\\literalblockneedspace}')
-            self.body.append('\\vspace{\\literalblockcaptiontopvspace}')
+            self.body.append('\\vspace{\\literalblockcaptiontopvspace}%')
-            self.body.append('\\captionof{literal-block}{')
+            self.body.append('\n\\SphinxSetupCaptionForVerbatim{literal-block}{')
             return
         self.body.append('\\caption{')
 

tests/test_directive_code.py

@@ -64,7 +64,7 @@ def test_code_block_caption_html(app, status, warning):
 def test_code_block_caption_latex(app, status, warning):
     app.builder.build_all()
     latex = (app.outdir / 'Python.tex').text(encoding='utf-8')
-    caption = '\\captionof{literal-block}{caption \\emph{test} rb}'
+    caption = '\\SphinxSetupCaptionForVerbatim{literal-block}{caption \\emph{test} rb}'
     assert caption in latex
 
 
@@ -229,7 +229,7 @@ def test_literalinclude_caption_html(app, status, warning):
 def test_literalinclude_caption_latex(app, status, warning):
     app.builder.build('index')
     latex = (app.outdir / 'Python.tex').text(encoding='utf-8')
-    caption = '\\captionof{literal-block}{caption \\textbf{test} py}'
+    caption = '\\SphinxSetupCaptionForVerbatim{literal-block}{caption \\textbf{test} py}'
     assert caption in latex