* [PATCH 1/2] doc: require Sphinx 2.44
2021-08-05 22:19 [PATCH 0/2] doc: update Sphinx build system Heinrich Schuchardt
@ 2021-08-05 22:20 ` Heinrich Schuchardt
2021-09-30 4:09 ` Simon Glass
2021-08-05 22:20 ` [PATCH 2/2] doc: fix Latex margins Heinrich Schuchardt
1 sibling, 1 reply; 6+ messages in thread
From: Heinrich Schuchardt @ 2021-08-05 22:20 UTC (permalink / raw)
To: Tom Rini; +Cc: Simon Glass, u-boot, Heinrich Schuchardt
Require Sphinx 2.44 to build the documentation.
Remove all code related to earlier versions.
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
---
doc/conf.py | 77 ++---------------------------------------
doc/sphinx/kerneldoc.py | 26 ++------------
2 files changed, 5 insertions(+), 98 deletions(-)
diff --git a/doc/conf.py b/doc/conf.py
index eb74b86aef..a375ad1b3a 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -31,7 +31,7 @@ from load_config import loadConfig
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.3'
+needs_sphinx = '2.44'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -118,19 +118,12 @@ if major >= 3:
else:
extensions.append('cdomain')
- if major == 1 and minor < 7:
- sys.stderr.write('WARNING: Sphinx 1.7 or greater will be required as of '
- 'the v2021.04 release\n')
# Ensure that autosectionlabel will produce unique names
autosectionlabel_prefix_document = True
autosectionlabel_maxdepth = 2
-# The name of the math extension changed on Sphinx 1.4
-if (major == 1 and minor > 3) or (major > 1):
- extensions.append("sphinx.ext.imgmath")
-else:
- extensions.append("sphinx.ext.pngmath")
+extensions.append("sphinx.ext.imgmath")
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -380,72 +373,6 @@ if cjk_cmd.find("Noto Sans CJK SC") >= 0:
\\setCJKmainfont{Noto Sans CJK SC}
'''
-# 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
- \\definecolor{NoteColor}{RGB}{204,255,255}
- \\definecolor{WarningColor}{RGB}{255,204,204}
- \\definecolor{AttentionColor}{RGB}{255,255,204}
- \\definecolor{ImportantColor}{RGB}{192,255,204}
- \\definecolor{OtherColor}{RGB}{204,204,204}
- \\newlength{\\mynoticelength}
- \\makeatletter\\newenvironment{coloredbox}[1]{%
- \\setlength{\\fboxrule}{1pt}
- \\setlength{\\fboxsep}{7pt}
- \\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}}}%
- {%
- \\ifthenelse%
- {\\equal{\\py@noticetype}{warning}}%
- {\\colorbox{WarningColor}{\\usebox{\\@tempboxa}}}%
- {%
- \\ifthenelse%
- {\\equal{\\py@noticetype}{attention}}%
- {\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}%
- {%
- \\ifthenelse%
- {\\equal{\\py@noticetype}{important}}%
- {\\colorbox{ImportantColor}{\\usebox{\\@tempboxa}}}%
- {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
- }%
- }%
- }%
- }\\makeatother
-
- \\makeatletter
- \\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{coloredbox}
- }
- \\makeatother
-
- '''
-
# With Sphinx 1.6, it is possible to change the Bg color directly
# by using:
# \definecolor{sphinxnoteBgColor}{RGB}{204,255,255}
diff --git a/doc/sphinx/kerneldoc.py b/doc/sphinx/kerneldoc.py
index e9857ab904..8189c33b9d 100644
--- a/doc/sphinx/kerneldoc.py
+++ b/doc/sphinx/kerneldoc.py
@@ -37,18 +37,8 @@ import glob
from docutils import nodes, statemachine
from docutils.statemachine import ViewList
from docutils.parsers.rst import directives, Directive
-
-#
-# AutodocReporter is only good up to Sphinx 1.7
-#
import sphinx
-
-Use_SSI = sphinx.__version__[:3] >= '1.7'
-if Use_SSI:
- from sphinx.util.docutils import switch_source_input
-else:
- from sphinx.ext.autodoc import AutodocReporter
-
+from sphinx.util.docutils import switch_source_input
import kernellog
__version__ = '1.0'
@@ -163,18 +153,8 @@ class KernelDocDirective(Directive):
return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
def do_parse(self, result, node):
- if Use_SSI:
- with switch_source_input(self.state, result):
- self.state.nested_parse(result, 0, node, match_titles=1)
- else:
- save = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
- self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
- self.state.memo.title_styles, self.state.memo.section_level = [], 0
- try:
- self.state.nested_parse(result, 0, node, match_titles=1)
- finally:
- self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = save
-
+ with switch_source_input(self.state, result):
+ self.state.nested_parse(result, 0, node, match_titles=1)
def setup(app):
app.add_config_value('kerneldoc_bin', None, 'env')
--
2.30.2
^ permalink raw reply related [flat|nested] 6+ messages in thread* [PATCH 2/2] doc: fix Latex margins
2021-08-05 22:19 [PATCH 0/2] doc: update Sphinx build system Heinrich Schuchardt
2021-08-05 22:20 ` [PATCH 1/2] doc: require Sphinx 2.44 Heinrich Schuchardt
@ 2021-08-05 22:20 ` Heinrich Schuchardt
2021-08-05 22:49 ` Tom Rini
2021-09-30 4:09 ` Simon Glass
1 sibling, 2 replies; 6+ messages in thread
From: Heinrich Schuchardt @ 2021-08-05 22:20 UTC (permalink / raw)
To: Tom Rini; +Cc: Simon Glass, u-boot, Heinrich Schuchardt
Adjust the Latex formatting to match Linux v5.13.1:
* add Latex margins
* reformat the code in doc/conf.py to match Linux
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
---
doc/conf.py | 31 +++++++++++++++++++------------
1 file changed, 19 insertions(+), 12 deletions(-)
diff --git a/doc/conf.py b/doc/conf.py
index a375ad1b3a..c24a359859 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -338,27 +338,34 @@ htmlhelp_basename = 'TheUBootdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-'papersize': 'a4paper',
+ # The paper size ('letterpaper' or 'a4paper').
+ 'papersize': 'a4paper',
-# The font size ('10pt', '11pt' or '12pt').
-'pointsize': '11pt',
+ # The font size ('10pt', '11pt' or '12pt').
+ 'pointsize': '11pt',
-# Latex figure (float) alignment
-#'figure_align': 'htbp',
+ # Latex figure (float) alignment
+ #'figure_align': 'htbp',
-# Don't mangle with UTF-8 chars
-'inputenc': '',
-'utf8extra': '',
+ # Don't mangle with UTF-8 chars
+ 'inputenc': '',
+ 'utf8extra': '',
-# Additional stuff for the LaTeX preamble.
+ # Set document margins
+ 'sphinxsetup': '''
+ hmargin=0.5in, vmargin=1in,
+ parsedliteralwraps=true,
+ verbatimhintsturnover=false,
+ ''',
+
+ # Additional stuff for the LaTeX preamble.
'preamble': '''
- % Use some font with UTF-8 support with XeLaTeX
+ % Use some font with UTF-8 support with XeLaTeX
\\usepackage{fontspec}
\\setsansfont{DejaVu Sans}
\\setromanfont{DejaVu Serif}
\\setmonofont{DejaVu Sans Mono}
- '''
+ ''',
}
# At least one book (translations) may have Asian characters
--
2.30.2
^ permalink raw reply related [flat|nested] 6+ messages in thread