[PATCH 0/2] Two cleanups for Sphinx conf.py

[PATCH 0/2] Two cleanups for Sphinx conf.py

[Mauro Carvalho Chehab]

Hi Jon,

Those patches are just cleanups for Documentation/conf.py. 

The first one removes a package usage directive for a LateX package
that it is not used. 

The second one moves some LaTeX preamble code that it is used only
on Sphinx 1.4 and 1.5 to a separate if. On Sphinx 1.6, the macros there
are silently ignored. While the conf.py becomes a little bit more complex,
it clearly marks the backward-compatible code, with IMHO, it is a
good idea, specially as some day, we may drop support for older Sphinx
versions.

None of those patches are mandatory. Feel free to apply any time you
want (or discard them, if you don't thing it is worth).

Please notice that the second patch will trivially conflict with a patch
I sent before, removing \\usepackage{adjustbox}.

I suspect that, if you apply those two patches before the one I sent eariler,
you'll avoid the conflict.

Anyway, if you apply all tree patches, you'll have a Latex 
Sphinx-independent preamble with just:

     'preamble': '''
       % Use some font with UTF-8 support with XeLaTeX
        \\usepackage{fontspec}
        \\setsansfont{DejaVu Serif}
        \\setromanfont{DejaVu Sans}
        \\setmonofont{DejaVu Sans Mono}
     '''
}

And all version-dependent preamble inserted after testing for the
Sphinx version.

Mauro Carvalho Chehab (2):
  docs-rst: conf.py: remove lscape from LaTeX preamble
  docs-rst: conf.py: only setup notice box colors if Sphinx < 1.6

 Documentation/conf.py | 65 ++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 43 insertions(+), 22 deletions(-)

-- 
2.13.5

[PATCH 1/2] docs-rst: conf.py: remove lscape from LaTeX preamble

[Mauro Carvalho Chehab]

Only the media book used this extension in the past, but
it is not required anymore.

Cleanup patch only.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/conf.py | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index f9054ab60cb1..38a606b07285 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -273,9 +273,6 @@ latex_elements = {
     'preamble': '''
         \\usepackage{ifthen}
 
-        % Allow generate some pages in landscape
-        \\usepackage{lscape}
-
         % Put notes in color and let them be inside a table
 	\\definecolor{NoteColor}{RGB}{204,255,255}
 	\\definecolor{WarningColor}{RGB}{255,204,204}
-- 
2.13.5

[PATCH 2/2] docs-rst: conf.py: only setup notice box colors if Sphinx < 1.6

[Mauro Carvalho Chehab]

Sphinx 1.5 added a new way to change backward colors for note
boxes, but kept backward compatibility with 1.4. On Sphinx 1.6,
the old way stopped working, in favor of a new less hackish
way.

Unfortunately, this is currently too buggy to be used, and
the old way doesn't work anymore. So, we have no option but
to stick with boring notice boxes.

One example of such bug is the notice that it is inside
struct v4l2_plane, at the "bytesused" field.

At least, add a notice about how to use, as maybe some day
the bug will vanish.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/conf.py | 62 +++++++++++++++++++++++++++++++++++----------------
 1 file changed, 43 insertions(+), 19 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 38a606b07285..b986eda20a05 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -271,6 +271,31 @@ latex_elements = {
 
 # Additional stuff for the LaTeX preamble.
     'preamble': '''
+	% Use some font with UTF-8 support with XeLaTeX
+        \\usepackage{fontspec}
+        \\setsansfont{DejaVu Serif}
+        \\setromanfont{DejaVu Sans}
+        \\setmonofont{DejaVu Sans Mono}
+
+	% To allow adjusting table sizes
+	\\usepackage{adjustbox}
+
+     '''
+}
+
+# Fix reference escape troubles with Sphinx 1.4.x
+if major == 1 and minor > 3:
+    latex_elements['preamble']  += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'
+
+if major == 1 and minor <= 4:
+    latex_elements['preamble']  += '\\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}'
+elif major == 1 and (minor > 5 or (minor == 5 and patch >= 3)):
+    latex_elements['sphinxsetup'] = 'hmargin=0.5in, vmargin=1in'
+    latex_elements['preamble']  += '\\fvset{fontsize=auto}\n'
+
+# Customize notice background colors on Sphinx < 1.6:
+if major == 1 and minor < 6:
+   latex_elements['preamble']  += '''
         \\usepackage{ifthen}
 
         % Put notes in color and let them be inside a table
@@ -322,27 +347,26 @@ latex_elements = {
         }
 	\\makeatother
 
-	% Use some font with UTF-8 support with XeLaTeX
-        \\usepackage{fontspec}
-        \\setsansfont{DejaVu Serif}
-        \\setromanfont{DejaVu Sans}
-        \\setmonofont{DejaVu Sans Mono}
-
-	% To allow adjusting table sizes
-	\\usepackage{adjustbox}
-
      '''
-}
 
-# Fix reference escape troubles with Sphinx 1.4.x
-if major == 1 and minor > 3:
-    latex_elements['preamble']  += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'
-
-if major == 1 and minor <= 4:
-    latex_elements['preamble']  += '\\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}'
-elif major == 1 and (minor > 5 or (minor == 5 and patch >= 3)):
-    latex_elements['sphinxsetup'] = 'hmargin=0.5in, vmargin=1in'
-    latex_elements['preamble']  += '\\fvset{fontsize=auto}\n'
+# With Sphinx 1.6, it is possible to change the Bg color directly
+# by using:
+#	\definecolor{sphinxnoteBgColor}{RGB}{204,255,255}
+#	\definecolor{sphinxwarningBgColor}{RGB}{255,204,204}
+#	\definecolor{sphinxattentionBgColor}{RGB}{255,255,204}
+#	\definecolor{sphinximportantBgColor}{RGB}{192,255,204}
+#
+# However, it require to use sphinx heavy box with:
+#
+#	\renewenvironment{sphinxlightbox} {%
+#		\\begin{sphinxheavybox}
+#	}
+#		\\end{sphinxheavybox}
+#	}
+#
+# Unfortunately, the implementation is buggy: if a note is inside a
+# table, it isn't displayed well. So, for now, let's use boring
+# black and white notes.
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
-- 
2.13.5

Re: [PATCH 0/2] Two cleanups for Sphinx conf.py

[Jonathan Corbet]

On Sun,  3 Sep 2017 16:12:44 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> Those patches are just cleanups for Documentation/conf.py. 
> 
> The first one removes a package usage directive for a LateX package
> that it is not used. 
> 
> The second one moves some LaTeX preamble code that it is used only
> on Sphinx 1.4 and 1.5 to a separate if. On Sphinx 1.6, the macros there
> are silently ignored. While the conf.py becomes a little bit more complex,
> it clearly marks the backward-compatible code, with IMHO, it is a
> good idea, specially as some day, we may drop support for older Sphinx
> versions.
> 
> None of those patches are mandatory. Feel free to apply any time you
> want (or discard them, if you don't thing it is worth).

OK, these are applied (and the adjustbox one too).

PDF generation seems to work pretty well at the moment, with one
exception: I don't get a table of contents in any of the files (just a
blank page saying "Contents").  Are you seeing something different?

Thanks,

jon

Re: [PATCH 0/2] Two cleanups for Sphinx conf.py

[Mauro Carvalho Chehab]

Em Fri, 8 Sep 2017 10:10:26 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Sun,  3 Sep 2017 16:12:44 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > Those patches are just cleanups for Documentation/conf.py. 
> > 
> > The first one removes a package usage directive for a LateX package
> > that it is not used. 
> > 
> > The second one moves some LaTeX preamble code that it is used only
> > on Sphinx 1.4 and 1.5 to a separate if. On Sphinx 1.6, the macros there
> > are silently ignored. While the conf.py becomes a little bit more complex,
> > it clearly marks the backward-compatible code, with IMHO, it is a
> > good idea, specially as some day, we may drop support for older Sphinx
> > versions.
> > 
> > None of those patches are mandatory. Feel free to apply any time you
> > want (or discard them, if you don't thing it is worth).  
> 
> OK, these are applied (and the adjustbox one too).

Thanks!
> 
> PDF generation seems to work pretty well at the moment, with one
> exception: I don't get a table of contents in any of the files (just a
> blank page saying "Contents").  Are you seeing something different?

That depends on the version. With Sphinx 1.4, the CONTENTS page is
filled with a LaTeX 1-depth ToC (e. g. 2 levels).

With Sphinx 1.6, the first time make pdfdocs is called, it doesn't
produce a CONTENTS page. It does if it is called twice.

I suspect that the difference here is that, with Sphinx up to
version 1.5, the Makefile created under Documentation/output/latex
calls xelatex several times:

%.pdf: %.tex
	$(PDFLATEX) $(LATEXOPTS) '$<'
	$(PDFLATEX) $(LATEXOPTS) '$<'
	$(PDFLATEX) $(LATEXOPTS) '$<'
	-$(MAKEINDEX) -s python.ist '$(basename $<).idx'
	$(PDFLATEX) $(LATEXOPTS) '$<'
	$(PDFLATEX) $(LATEXOPTS) '$<'



With Sphinx 1.6, it calls it only once:

%.pdf: %.tex FORCE_MAKE
	$(PDFLATEX) $(LATEXMKOPTS) '$<'

That seems another regression on Sphinx 1.6.

Regards,
Mauro