Am 19.12.2016 um 11:25 schrieb Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx>: > On Mon, 19 Dec 2016, Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> wrote: >> It could be interesting to print some error message if someone tries >> to build with an older version or if the version can't be detected, >> asking the user to upgrade Sphinx. > > This will do it. > > BR, > Jani. > > diff --git a/Documentation/conf.py b/Documentation/conf.py > index 1ac958c0333d..b763271e2035 100644 > --- a/Documentation/conf.py > +++ b/Documentation/conf.py > @@ -29,7 +29,7 @@ from load_config import loadConfig > # -- General configuration ------------------------------------------------ > > # If your documentation needs a minimal Sphinx version, state it here. > -#needs_sphinx = '1.0' > +needs_sphinx = '1.2' > > # Add any Sphinx extension module names here, as strings. They can be > # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom > > I agree to use sphinx.version_info and 'needs_sphix'. But while I'am testing: * sphinx 1.5 with * docutils 0.13.1 I got several fails more. I fixed some of them (see patch below) but there is more work to do, to get a PDF build. Read on my experience: While I'am testing with the sphinx 1.5 tag, I got the next error:: WARNING: primary_domain 'C' not found, ignored. This message (check) comes from sphinx commit: https://github.com/sphinx-doc/sphinx/commit/ea778e7633b39b7fd150516922e5d819e6d7c1a8 It seems, that Sphinx >= 1.5 needs the lowercase of 'c' in conf.py: -primary_domain = 'C' +primary_domain = 'c' I added this also to the patch below. With this patch, the HTML build failed with exception: File "....../python3.5/site-packages/docutils/writers/_html_base.py", line 671, in depart_document assert not self.context, 'len(context) = %s' % len(self.context) AssertionError: len(context) = 1 I have not yet looked closer, but I guess this is a bug somewhere in the HTML builder in docutils or sphinx. When I try to build PDF, I got the next error::: ! LaTeX Error: Option clash for package geometry. See the LaTeX manual or LaTeX Companion for explanation. Type H <return> for immediate help. ... l.41 The package geometry has already been loaded with options: [margin=1in,marginparwidth=0.5in] There has now been an attempt to load it with options [margin=0.5in, top=1in, bottom=1in] Adding the global options: margin=1in,marginparwidth=0.5in,margin=0.5in, top=1in, bottom=1in to your \documentclass declaration may fix this. Try typing <return> to proceed. This is a conflict of Sphinx 1.5 geometry support: https://github.com/sphinx-doc/sphinx/commit/34f1ce17fd503b50e8b6b0cee8f43eae6d6a9b73 and the preamble which comes from docs-next's commit 85c21e5c, adding geometry to latex preamble: 'preamble': ''' + % Adjust margins + \\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry} So I fixed this (see patch below), after that, I can build PDF except from media. Building PDF from media's LaTeX fails with:: ! Missing \endgroup inserted. <inserted text> \endgroup l.16028 \unskip}\relax } \\ I've inserted something that you may have forgotten. ... ! Package xcolor Error: Undefined color `spx@notice@bordercolor'. ... It seems, that sphinx 1.5 does not support *admonitions* in tables, (see /media/uapi/v4l/buffer.rst line 132) and the old workaround in the preamble (which worked for Sphinx < 1.5) does no longer work with Sphinx 1.5. In Sphinx 1.5. the LaTeX writer has been rewritten so that most of the LaTeX customizing from 1.4 will no longer work :-o BTW: IMO we should not customize theming in LaTeX pre Sphinx 1.5, since there is no API. With Sphinx 1.5 even if there is no LaTeX API, we can see that the LaTeX builder development consolidates (which might allow more robust customizing). Anyway, I vote for 'less as possible' LaTeX theming/customizing. E.g. here is how the handling of admonitions was changed: https://github.com/sphinx-doc/sphinx/commit/e5db9da45d31014b99615748b5611892a8f9a35d To summarize my Sphinx 1.5 & Docutils 0.13.1 experiences: * can't build HTML * PDF build fails when building media's PDF Sorry that I haven't solved all problems, but the patch below might be a good starting point for Sphinx 1.5 support. -- Markus -- ------- diff --git a/Documentation/conf.py b/Documentation/conf.py index 1ac958c..dd6471d 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -17,8 +17,7 @@ import os import sphinx # Get Sphinx version -major, minor, patch = map(int, sphinx.__version__.split(".")) - +major, minor, patch = sphinx.version_info[:3] # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -29,7 +28,7 @@ from load_config import loadConfig # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +needs_sphinx = '1.2' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -135,7 +134,7 @@ pygments_style = 'sphinx' # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False -primary_domain = 'C' +primary_domain = 'c' highlight_language = 'none' # -- Options for HTML output ---------------------------------------------- @@ -256,24 +255,27 @@ htmlhelp_basename = 'TheLinuxKerneldoc' # -- Options for LaTeX output --------------------------------------------- latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -'papersize': 'a4paper', - -# The font size ('10pt', '11pt' or '12pt'). -'pointsize': '8pt', - -# Latex figure (float) alignment -#'figure_align': 'htbp', - -# Don't mangle with UTF-8 chars -'inputenc': '', -'utf8extra': '', - -# Additional stuff for the LaTeX preamble. - 'preamble': ''' - % Adjust margins - \\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry} + # The paper size ('letterpaper' or 'a4paper'). + 'papersize': 'a4paper', + + # The font size ('10pt', '11pt' or '12pt'). + 'pointsize': '8pt', + + # Latex figure (float) alignment + #'figure_align': 'htbp', + + # Don't mangle with UTF-8 chars + 'inputenc': '', + 'utf8extra': '', + 'preamble' : ''' +% To allow adjusting table sizes +\\usepackage{adjustbox} +''' +} +if major == 1 and minor < 5: + # Adjust margins + latex_elements['preamble'] = ''' % Allow generate some pages in landscape \\usepackage{lscape} @@ -326,11 +328,15 @@ latex_elements = { \\setromanfont{DejaVu Sans} \\setmonofont{DejaVu Sans Mono} - % To allow adjusting table sizes - \\usepackage{adjustbox} - ''' -} + + +geometry = '\\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}' +if major == 1 and minor < 5: + # Adjust margins + latex_elements['preamble'] = (geometry + '\n' + latex_elements['preamble']) +else: + latex_elements['geometry'] = geometry # Fix reference escape troubles with Sphinx 1.4.x if major == 1 and minor > 3: diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index df0419c..cf13ff3 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -44,7 +44,7 @@ from sphinx.domains.c import CDomain as Base_CDomain __version__ = '1.0' # Get Sphinx version -major, minor, patch = map(int, sphinx.__version__.split(".")) +major, minor, patch = sphinx.version_info[:3] def setup(app): -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
