Em Tue, 9 Aug 2016 18:19:14 -0700
"Luis R. Rodriguez" <mcg...@kernel.org> escreveu:
> I'm excited to see the new documentation format, so I'm changing my
> documentation in the pending patches I have to use it. I however
> cannot generate anything other than the main
>
> Documentation/output/pdf/Kernel.pdf
>
> How can I see in PDF the other documentation?
>
> I'm using:
>
> make DOCBOOKS="" pdfdocs
>
> The Documentation/output/pdf/Kernel.pdf only has a bit of the
> documentation on how to write docs, nothing else. Using htmldocs as a
> target works but I am not a fan of that output.
Hi Luis,
Unfortunately, on my tests with Sphinx, I noticed that pdf output is
not actually working fine. It relies on a tool called rst2pdf. On
my tests, I noticed that:
- rst2pdf is completely broken with Sphinx 1.3.x;
- rst2pdf doesn't handle complex documents, even with Sphinx 1.4.5;
- rst2pdf always report a successful build, even when it fails;
- I also consulted a developer with years of experience with Sphinx: he
recommended removing the media book from the pdf build, as he doesn't
know any fixup or replacement for the tool that would work for the
media docs.
If you want to play with PDF output, you should take a look on this patch:
https://patchwork.kernel.org/patch/9231687/
(commit 520a247760f750307b53db905a10a17df1700f3b)
Reverting it or adding your document main rst file there would let you play
with pdfdocs, if you're using Sphinx version 1.4.x.
If you revert it, you'll also need the enclosed patch.
Regards,
Cheers,
Mauro
---
doc-rst: build the dynamic rst files for non-html doc targets
Right now, the media makefile is called only for html docs.
Call it also for the other documentation targets.
NOTICE: Should not be applied upstream!
The pdf target won't actually build a PDF, because rst2pdf can't
handle complex documents and will fail with the media one.
Signed-off-by: Mauro Carvalho Chehab <mche...@osg.samsung.com>
diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index 857f1e273418..e90167ba474d 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -49,13 +49,16 @@ ifeq ($(HAVE_RST2PDF),0)
$(warning The Python 'rst2pdf' module was not found. Make sure you have
the module installed to produce PDF output.)
@echo " SKIP Sphinx $@ target."
else # HAVE_RST2PDF
+ $(MAKE) BUILDDIR=$(BUILDDIR) -f $(srctree)/Documentation/media/Makefile
$@
$(call cmd,sphinx,pdf)
endif # HAVE_RST2PDF
epubdocs:
+ $(MAKE) BUILDDIR=$(BUILDDIR) -f $(srctree)/Documentation/media/Makefile
$@
$(call cmd,sphinx,epub)
xmldocs:
+ $(MAKE) BUILDDIR=$(BUILDDIR) -f $(srctree)/Documentation/media/Makefile
$@
$(call cmd,sphinx,xml)
# no-ops for the Sphinx toolchain
diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index 39e2d766dbe3..79784e848fc0 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -11,6 +11,9 @@ FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst
net.h.rst video.h.rst \
TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
htmldocs: $(BUILDDIR) ${TARGETS}
+epubdocs: $(BUILDDIR) ${TARGETS}
+xmldocs: $(BUILDDIR) ${TARGETS}
+pdfdocs: $(BUILDDIR) ${TARGETS}
$(BUILDDIR):
$(Q)mkdir -p $@
