u-boot.lists.denx.de archive mirror
 help / color / mirror / Atom feed
* [PATCH 0/2] doc: update Sphinx build system
@ 2021-08-05 22:19 Heinrich Schuchardt
  2021-08-05 22:20 ` [PATCH 1/2] doc: require Sphinx 2.44 Heinrich Schuchardt
  2021-08-05 22:20 ` [PATCH 2/2] doc: fix Latex margins Heinrich Schuchardt
  0 siblings, 2 replies; 6+ messages in thread
From: Heinrich Schuchardt @ 2021-08-05 22:19 UTC (permalink / raw)
  To: Tom Rini; +Cc: Simon Glass, u-boot, Heinrich Schuchardt

We require Sphinx 2.44. Adjust the coding accordingly.

In Linux the margins of Latex documents were fixed. Update our files
accordingly.

Heinrich Schuchardt (2):
  doc: require Sphinx 2.44
  doc: fix Latex margins

 doc/conf.py             | 108 ++++++++--------------------------------
 doc/sphinx/kerneldoc.py |  26 ++--------
 2 files changed, 24 insertions(+), 110 deletions(-)

--
2.30.2


^ permalink raw reply	[flat|nested] 6+ messages in thread

* [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

* Re: [PATCH 2/2] doc: fix Latex margins
  2021-08-05 22:20 ` [PATCH 2/2] doc: fix Latex margins Heinrich Schuchardt
@ 2021-08-05 22:49   ` Tom Rini
  2021-09-30  4:09   ` Simon Glass
  1 sibling, 0 replies; 6+ messages in thread
From: Tom Rini @ 2021-08-05 22:49 UTC (permalink / raw)
  To: Heinrich Schuchardt; +Cc: Simon Glass, u-boot

[-- Attachment #1: Type: text/plain, Size: 401 bytes --]

On Fri, Aug 06, 2021 at 12:20:01AM +0200, Heinrich Schuchardt wrote:

> 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>

Is a larger re-sync effort not warranted?  Or are we not aiming to
/ needing to so closely follow the kernel here?

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH 2/2] doc: fix Latex margins
  2021-08-05 22:20 ` [PATCH 2/2] doc: fix Latex margins Heinrich Schuchardt
  2021-08-05 22:49   ` Tom Rini
@ 2021-09-30  4:09   ` Simon Glass
  1 sibling, 0 replies; 6+ messages in thread
From: Simon Glass @ 2021-09-30  4:09 UTC (permalink / raw)
  To: Heinrich Schuchardt; +Cc: Tom Rini, U-Boot Mailing List

On Thu, 5 Aug 2021 at 16:20, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>
> 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(-)

Reviewed-by: Simon Glass <sjg@chromium.org>

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH 1/2] doc: require Sphinx 2.44
  2021-08-05 22:20 ` [PATCH 1/2] doc: require Sphinx 2.44 Heinrich Schuchardt
@ 2021-09-30  4:09   ` Simon Glass
  0 siblings, 0 replies; 6+ messages in thread
From: Simon Glass @ 2021-09-30  4:09 UTC (permalink / raw)
  To: Heinrich Schuchardt; +Cc: Tom Rini, U-Boot Mailing List

On Thu, 5 Aug 2021 at 16:20, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote:
>
> 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(-)

Reviewed-by: Simon Glass <sjg@chromium.org>

But please add a motivation for this patch.

^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2021-09-30  4:15 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
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-09-30  4:09   ` Simon Glass
2021-08-05 22:20 ` [PATCH 2/2] doc: fix Latex margins Heinrich Schuchardt
2021-08-05 22:49   ` Tom Rini
2021-09-30  4:09   ` Simon Glass

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).