From 3eb6cd6834c356f40e1633a0ced4ff9a4c59936b Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 10 Aug 2016 18:54:09 +0300 Subject: Documentation: exclude media documentation from pdf generation Although pdflatex is more robust than rst2pdf, building media documentation pdf still fails. Exclude media documentation from pdf generation for now. Signed-off-by: Jani Nikula Acked-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index 96b7aa66c89c..827dafc515b1 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -268,7 +268,9 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'TheLinuxKernel.tex', 'The Linux Kernel Documentation', + ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', + 'The kernel development community', 'manual'), + ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide', 'The kernel development community', 'manual'), ] -- cgit v1.2.3 From 606b9ac81a63ab3adb7e61206b9ae34ee186a89d Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 13 Aug 2016 16:12:42 +0200 Subject: doc-rst: generic way to build only sphinx sub-folders Add a generic way to build only a reST sub-folder with or without a individual *build-theme*. * control *sub-folders* by environment SPHINXDIRS * control *build-theme* by environment SPHINX_CONF Folders with a conf.py file, matching $(srctree)/Documentation/*/conf.py can be build and distributed *stand-alone*. E.g. to compile only the html of 'media' and 'gpu' folder use:: make SPHINXDIRS="media gpu" htmldocs To use an additional sphinx-build configuration (*build-theme*) set the name of the configuration file to SPHINX_CONF. E.g. to compile only the html of 'media' with the *nit-picking* build use:: make SPHINXDIRS=media SPHINX_CONF=conf_nitpick.py htmldocs With this, the Documentation/conf.py is read first and updated with the configuration values from the Documentation/media/conf_nitpick.py. Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index 827dafc515b1..43e41ed74584 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -19,6 +19,7 @@ import os # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('sphinx')) +from load_config import loadConfig # -- General configuration ------------------------------------------------ @@ -421,3 +422,9 @@ pdf_documents = [ # line arguments. kerneldoc_bin = '../scripts/kernel-doc' kerneldoc_srctree = '..' + +# ------------------------------------------------------------------------------ +# Since loadConfig overwrites settings from the global namespace, it has to be +# the last statement in the conf.py file +# ------------------------------------------------------------------------------ +loadConfig(globals()) -- cgit v1.2.3 From a69ab10869941f45b5f1291ec482df1e9bd7895f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:36 -0300 Subject: docs-rst: remove a rst2pdf left over code The usage of rst2pdf was replaced by pdflatex on a previous patch. Remove the left-over code at conf.py. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 7 ------- 1 file changed, 7 deletions(-) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index 43e41ed74584..1c6d9da5d1b5 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -31,13 +31,6 @@ from load_config import loadConfig # ones. extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include'] -# Gracefully handle missing rst2pdf. -try: - import rst2pdf - extensions += ['rst2pdf.pdfbuilder'] -except ImportError: - pass - # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -- cgit v1.2.3 From caee5cdede9c9b3562abd6a93c71e791577802ad Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:37 -0300 Subject: docs-rst: allow generating some LaTeX pages in landscape Portrait is too small for some tables used at the media docs. So, allow documents to tell Sphinx to generate some pages in landscape by using: .. raw:: latex \begin{landscape} .. raw:: latex \end{landscape} Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index 1c6d9da5d1b5..38b240073336 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -246,16 +246,19 @@ htmlhelp_basename = 'TheLinuxKerneldoc' latex_elements = { # The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', +'papersize': 'a4paper', # The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', +'pointsize': '10pt', # Latex figure (float) alignment #'figure_align': 'htbp', + +# Additional stuff for the LaTeX preamble. + 'preamble': ''' + % Allow generate some pages in landscape + \\usepackage{lscape} + ''' } # Grouping the document tree into LaTeX files. List of tuples -- cgit v1.2.3 From 60459774659267569b4d944fcecb372ad0c48629 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:38 -0300 Subject: docs-rst: improve output for .. notes:: on LaTeX The output for those notes are bad in pdf, as they're not in a box with a different color. Also, it causes the output to not build if the note is inside a table. Change its implementation to avoid the above troubles. The logic there came from: https://stackoverflow.com/questions/606746/how-to-customize-an-existing-latex-environment-without-interfering-with-other-en Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index 38b240073336..429183a03b92 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -258,6 +258,29 @@ latex_elements = { 'preamble': ''' % Allow generate some pages in landscape \\usepackage{lscape} + + % Put notes in gray color and let them be inside a table + + \\definecolor{MyGray}{rgb}{0.80,0.80,0.80} + + \\makeatletter\\newenvironment{graybox}{% + \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\columnwidth}}{\\end{minipage}\\end{lrbox}% + \\colorbox{MyGray}{\\usebox{\\@tempboxa}} + }\\makeatother + + \\makeatletter + \\renewenvironment{notice}[2]{ + \\begin{graybox} + \\bf\\it + \\def\\py@noticetype{#1} + \\par\\strong{#2} + \\csname py@noticestart@#1\\endcsname + } + { + \\csname py@noticeend@\\py@noticetype\\endcsname + \\end{graybox} + } + \\makeatother ''' } -- cgit v1.2.3 From a682ec4ba10c88231cdbb8bb9823b2cc749d6364 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:39 -0300 Subject: docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output pdflatex doesn't accept using some UTF-8 chars, like "equal or less than" or "equal or greater than" chars. However, the media documents use them. So, we need to use XeLaTeX for conversion, and a font that accepts such characters. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index 429183a03b92..06e6db916d2f 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -254,6 +254,10 @@ latex_elements = { # Latex figure (float) alignment #'figure_align': 'htbp', +# Don't mangle with UTF-8 chars +'inputenc': '', +'utf8extra': '', + # Additional stuff for the LaTeX preamble. 'preamble': ''' % Allow generate some pages in landscape @@ -281,6 +285,13 @@ latex_elements = { \\end{graybox} } \\makeatother + + % Use some font with UTF-8 support with XeLaTeX + \\usepackage{fontspec} + \\setsansfont{DejaVu Serif} + \\setromanfont{DejaVu Sans} + \\setmonofont{DejaVu Sans Mono} + ''' } -- cgit v1.2.3 From 85c21e5c3ee74fb75d690c57f7066bae7e2dca55 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:40 -0300 Subject: docs-rst: better adjust margins and font size As we have big tables, reduce the left/right margins and decrease the point size to 8pt. Visually, it is still good enough, and now less tables are too big to be displayed. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index 06e6db916d2f..61b71ae60ad0 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -249,7 +249,7 @@ latex_elements = { 'papersize': 'a4paper', # The font size ('10pt', '11pt' or '12pt'). -'pointsize': '10pt', +'pointsize': '8pt', # Latex figure (float) alignment #'figure_align': 'htbp', @@ -260,6 +260,9 @@ latex_elements = { # Additional stuff for the LaTeX preamble. 'preamble': ''' + % Adjust margins + \\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry} + % Allow generate some pages in landscape \\usepackage{lscape} -- cgit v1.2.3 From d4fe7e14e4ff5d90286397180831a35df502969e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 16 Aug 2016 13:25:43 -0300 Subject: docs-rst: enable the Sphinx math extension This extension will be used by the media books. The name of the math image extension changed on Sphinx 1.4.x, according with: http://www.sphinx-doc.org/en/stable/ext/math.html#module-sphinx.ext.imgmath Let's autodetect, to keep building with versions < 1.4. Suggested-by: Markus Heiser Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index 61b71ae60ad0..23e2f0bbcfc8 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -14,6 +14,11 @@ import sys import os +import sphinx + +# Get Sphinx version +major, minor, patch = map(int, sphinx.__version__.split(".")) + # 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 @@ -31,6 +36,12 @@ from load_config import loadConfig # ones. extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include'] +# The name of the math extension changed on Sphinx 1.4 +if minor > 3: + extensions.append("sphinx.ext.imgmath") +else: + extensions.append("sphinx.ext.pngmath") + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -- cgit v1.2.3 From e8f5c617f26626ef4915ffa176f4ae02c9e08531 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 22 Aug 2016 15:16:21 -0600 Subject: doc-rst: add boilerplate to customize c-domain Add a sphinx-extension to customize the sphinx c-domain. No functional changes right yet, just the boilerplate code. Signed-off-by: Markus Heiser [ jc: coding-style tweak ] Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index 23e2f0bbcfc8..88c377d468d0 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -34,7 +34,7 @@ from load_config import loadConfig # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include'] +extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include', 'cdomain'] # The name of the math extension changed on Sphinx 1.4 if minor > 3: -- cgit v1.2.3 From aa4e37a3d13679dccf7945dd864375b698cf0df9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 19 Aug 2016 09:49:38 -0300 Subject: docs-rst: conf.py: adjust the size of .. note:: tag While the current implementation works well when using as a paragraph, it doesn't work properly if inside a table. As we have quite a few such cases, fix the logic to take the column size into account. PS.: I took the logic there from the latest version of Sphinx.sty Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index 88c377d468d0..aaa3f70aafcb 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -282,7 +282,13 @@ latex_elements = { \\definecolor{MyGray}{rgb}{0.80,0.80,0.80} \\makeatletter\\newenvironment{graybox}{% - \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\columnwidth}}{\\end{minipage}\\end{lrbox}% + \\newlength{\\py@noticelength} + \\setlength{\\fboxrule}{1pt} + \\setlength{\\fboxsep}{7pt} + \\setlength{\\py@noticelength}{\\linewidth} + \\addtolength{\\py@noticelength}{-2\\fboxsep} + \\addtolength{\\py@noticelength}{-2\\fboxrule} + \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\py@noticelength}}{\\end{minipage}\\end{lrbox}% \\colorbox{MyGray}{\\usebox{\\@tempboxa}} }\\makeatother -- cgit v1.2.3 From 41cff161fe99d1c6a773becc2250a1dc3ac035ff Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 21 Aug 2016 15:23:03 -0300 Subject: docs-rst: Use better colors for note/warning/attention boxes Instead of painting the box with gray, let's use a colored box. IMHO, that makes easier to warn users about some issue pointed by the Sphinx. It also matches to what we do already with the HTML output. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index aaa3f70aafcb..2a02a817b1a0 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -277,11 +277,12 @@ latex_elements = { % Allow generate some pages in landscape \\usepackage{lscape} - % Put notes in gray color and let them be inside a table - - \\definecolor{MyGray}{rgb}{0.80,0.80,0.80} - - \\makeatletter\\newenvironment{graybox}{% + % Put notes in color and let them be inside a table + \\definecolor{NoteColor}{RGB}{204,255,255} + \\definecolor{WarningColor}{RGB}{255,204,204} + \\definecolor{AttentionColor}{RGB}{255,255,204} + \\definecolor{OtherColor}{RGB}{204,204,204} + \\makeatletter\\newenvironment{coloredbox}[1]{% \\newlength{\\py@noticelength} \\setlength{\\fboxrule}{1pt} \\setlength{\\fboxsep}{7pt} @@ -289,20 +290,33 @@ latex_elements = { \\addtolength{\\py@noticelength}{-2\\fboxsep} \\addtolength{\\py@noticelength}{-2\\fboxrule} \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\py@noticelength}}{\\end{minipage}\\end{lrbox}% - \\colorbox{MyGray}{\\usebox{\\@tempboxa}} + \\ifthenelse% + {\\equal{\\py@noticetype}{note}}% + {\\colorbox{NoteColor}{\\usebox{\\@tempboxa}}}% + {% + \\ifthenelse% + {\\equal{\\py@noticetype}{warning}}% + {\\colorbox{WarningColor}{\\usebox{\\@tempboxa}}}% + {% + \\ifthenelse% + {\\equal{\\py@noticetype}{attention}}% + {\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}% + {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}% + }% + }% }\\makeatother \\makeatletter - \\renewenvironment{notice}[2]{ - \\begin{graybox} - \\bf\\it + \\renewenvironment{notice}[2]{% \\def\\py@noticetype{#1} + \\begin{coloredbox}{#1} + \\bf\\it \\par\\strong{#2} \\csname py@noticestart@#1\\endcsname } { \\csname py@noticeend@\\py@noticetype\\endcsname - \\end{graybox} + \\end{coloredbox} } \\makeatother -- cgit v1.2.3 From ba1377fba7047a86c31981363cbd9e65b1ca2763 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 21 Aug 2016 15:23:04 -0300 Subject: docs-rst: Fix an warning when in interactive mode When XeLaTeX is in interactive mode, it complains that py@noticelength already exists. Rename it and declare it only once to avoid such messages. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index 2a02a817b1a0..85e9f16b1d98 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -282,14 +282,14 @@ latex_elements = { \\definecolor{WarningColor}{RGB}{255,204,204} \\definecolor{AttentionColor}{RGB}{255,255,204} \\definecolor{OtherColor}{RGB}{204,204,204} + \\newlength{\\mynoticelength} \\makeatletter\\newenvironment{coloredbox}[1]{% - \\newlength{\\py@noticelength} \\setlength{\\fboxrule}{1pt} \\setlength{\\fboxsep}{7pt} - \\setlength{\\py@noticelength}{\\linewidth} - \\addtolength{\\py@noticelength}{-2\\fboxsep} - \\addtolength{\\py@noticelength}{-2\\fboxrule} - \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\py@noticelength}}{\\end{minipage}\\end{lrbox}% + \\setlength{\\mynoticelength}{\\linewidth} + \\addtolength{\\mynoticelength}{-2\\fboxsep} + \\addtolength{\\mynoticelength}{-2\\fboxrule} + \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\mynoticelength}}{\\end{minipage}\\end{lrbox}% \\ifthenelse% {\\equal{\\py@noticetype}{note}}% {\\colorbox{NoteColor}{\\usebox{\\@tempboxa}}}% -- cgit v1.2.3 From ca7bfe2c8d9f3aee469a3a36110a95ebb511ee20 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 22 Aug 2016 11:04:49 -0300 Subject: docs-rst: add package adjustbox We need adjustbox to allow adjusting the size of tables that are bigger than the line width. There are quite a few of them at the media books. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index 85e9f16b1d98..ab484e56e23c 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -326,6 +326,9 @@ latex_elements = { \\setromanfont{DejaVu Sans} \\setmonofont{DejaVu Sans Mono} + % To allow adjusting table sizes + \\usepackage{adjustbox} + ''' } -- cgit v1.2.3 From f0ddda3e94136e14320be63f5dfb22114a4877cc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:07:38 -0300 Subject: docs-rst: create a book for the development process Now that the files at Documentation/development-process/ were converted to ReST, make create a book at Sphinx. As we'll have other books related to the development process, we'll add it as a sub-book. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation/conf.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index ab484e56e23c..d9fd92007fd6 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -338,6 +338,8 @@ latex_elements = { latex_documents = [ ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', 'The kernel development community', 'manual'), + ('development-process/index', 'development-process.tex', 'Linux Kernel Development Documentation', + 'The kernel development community', 'manual'), ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide', 'The kernel development community', 'manual'), ] -- cgit v1.2.3