| Message ID | 0e610cbb57e85864b23d2b8fffa65c6b137daaac.1607597287.git.mchehab+huawei@kernel.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Address issues with PDF output at media uAPI docs | expand |
On Thu, 10 Dec 2020 11:55:40 +0100 Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote: > The PDF generator has a logic to detect the proper way to > setup the page margins. By default, the page has about > 14.8 cm, which is too short to display some tables and literal > blocks. So, previous patches changed it to be around 17.5 cm, > but the logic only works with Sphinx version 1.x.x. > > Fix it. > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jonathan Corbet <corbet@lwn.net> Feel free to route this one with the rest of the set. Someday it might be nice to isolate all of the latex stuff into conf-latex.py or some such so most of us don't have to look at it..:) Thanks, jon
Em Thu, 10 Dec 2020 07:48:45 -0700 Jonathan Corbet <corbet@lwn.net> escreveu: > On Thu, 10 Dec 2020 11:55:40 +0100 > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote: > > > The PDF generator has a logic to detect the proper way to > > setup the page margins. By default, the page has about > > 14.8 cm, which is too short to display some tables and literal > > blocks. So, previous patches changed it to be around 17.5 cm, > > but the logic only works with Sphinx version 1.x.x. > > > > Fix it. > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > > Acked-by: Jonathan Corbet <corbet@lwn.net> > > Feel free to route this one with the rest of the set. > > Someday it might be nice to isolate all of the latex stuff into > conf-latex.py or some such so most of us don't have to look at it..:) Yeah, makes sense. Btw, just gave another trial of rst2pdf (sent the RFC patch adding support for it)... Still doesn't work: lots of documents are produced with zero size :-( Thanks, Mauro
Em Thu, 10 Dec 2020 17:01:19 +0100 Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu: > Add an experimental PDF builder using rst2pdf > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> I opened an issue at: https://github.com/rst2pdf/rst2pdf/issues/958 Let's hope someone at rst2pdf could help fixing this ;-) Regards, Mauro > --- > Documentation/Makefile | 5 +++++ > Documentation/conf.py | 21 +++++++++++++++------ > Documentation/userspace-api/media/Makefile | 1 + > Makefile | 4 ++-- > 4 files changed, 23 insertions(+), 8 deletions(-) > > diff --git a/Documentation/Makefile b/Documentation/Makefile > index 61a7310b49e0..c3c8fb10f94e 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -115,6 +115,10 @@ pdfdocs: latexdocs > > endif # HAVE_PDFLATEX > > +rst2pdf: > + @$(srctree)/scripts/sphinx-pre-install --version-check > + @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,pdf,$(var),pdf,$(var))) > + > epubdocs: > @$(srctree)/scripts/sphinx-pre-install --version-check > @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) > @@ -140,6 +144,7 @@ dochelp: > @echo ' htmldocs - HTML' > @echo ' latexdocs - LaTeX' > @echo ' pdfdocs - PDF' > + @echo ' rst2pdf - PDF, using experimental rst2pdf support' > @echo ' epubdocs - EPUB' > @echo ' xmldocs - XML' > @echo ' linkcheckdocs - check for broken external links' > diff --git a/Documentation/conf.py b/Documentation/conf.py > index 66e121df59cd..6f2788aac81e 100644 > --- a/Documentation/conf.py > +++ b/Documentation/conf.py > @@ -123,6 +123,12 @@ if (major == 1 and minor > 3) or (major > 1): > else: > extensions.append("sphinx.ext.pngmath") > > +# Enable experimental rst2pdf, if available > +try: > + extensions.append("rst2pdf.pdfbuilder") > +except: > + sys.stderr.write('rst2pdf extension not available.\n') > + > # Add any paths that contain templates here, relative to this directory. > templates_path = ['_templates'] > > @@ -614,12 +620,15 @@ epub_exclude_files = ['search.html'] > # > # See the Sphinx chapter of https://ralsina.me/static/manual.pdf > # > -# FIXME: Do not add the index file here; the result will be too big. Adding > -# multiple PDF files here actually tries to get the cross-referencing right > -# *between* PDF files. > -pdf_documents = [ > - ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'), > -] > + > +# Add all LaTeX files to PDF documents as well > +pdf_documents = [] > +for l in latex_documents: > + doc = l[0] > + fn = l[1].replace(".tex", "") > + name = l[2] > + authors = l[3] > + pdf_documents.append((doc, fn, name, authors)) > > # kernel-doc extension configuration for running Sphinx directly (e.g. by Read > # the Docs). In a normal build, these are supplied from the Makefile via command > diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile > index 81a4a1a53bce..8c6b3ac4ecb0 100644 > --- a/Documentation/userspace-api/media/Makefile > +++ b/Documentation/userspace-api/media/Makefile > @@ -59,6 +59,7 @@ all: $(IMGDOT) $(BUILDDIR) ${TARGETS} > html: all > epub: all > xml: all > +pdf: all > latex: $(IMGPDF) all > linkcheck: > > diff --git a/Makefile b/Makefile > index 43ecedeb3f02..db4043578eec 100644 > --- a/Makefile > +++ b/Makefile > @@ -264,7 +264,7 @@ no-dot-config-targets := $(clean-targets) \ > cscope gtags TAGS tags help% %docs check% coccicheck \ > $(version_h) headers headers_% archheaders archscripts \ > %asm-generic kernelversion %src-pkg dt_binding_check \ > - outputmakefile > + outputmakefile rst2pdf > no-sync-config-targets := $(no-dot-config-targets) %install kernelrelease > single-targets := %.a %.i %.ko %.lds %.ll %.lst %.mod %.o %.s %.symtypes %/ > > @@ -1654,7 +1654,7 @@ $(help-board-dirs): help-%: > > # Documentation targets > # --------------------------------------------------------------------------- > -DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \ > +DOC_TARGETS := xmldocs latexdocs pdfdocs rst2pdf htmldocs epubdocs cleandocs \ > linkcheckdocs dochelp refcheckdocs > PHONY += $(DOC_TARGETS) > $(DOC_TARGETS): Thanks, Mauro
diff --git a/Documentation/conf.py b/Documentation/conf.py index ed2b43ec7754..66e121df59cd 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -375,9 +375,10 @@ if cjk_cmd.find("Noto Sans CJK SC") >= 0: if major == 1 and minor > 3: latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n' +# Set page margins 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)): +elif (major == 1 and (minor > 5 or (minor == 5 and patch >= 3))) or (major > 1): latex_elements['sphinxsetup'] = 'hmargin=0.5in, vmargin=1in' latex_elements['preamble'] += '\\fvset{fontsize=auto}\n'
The PDF generator has a logic to detect the proper way to setup the page margins. By default, the page has about 14.8 cm, which is too short to display some tables and literal blocks. So, previous patches changed it to be around 17.5 cm, but the logic only works with Sphinx version 1.x.x. Fix it. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> --- Documentation/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)