Re: Making pdfdocs with sphinx - only select rst targets

[Mauro Carvalho Chehab <mchehab@infradead.org>]

Em Tue, 9 Aug 2016 18:19:14 -0700
"Luis R. Rodriguez" <mcgrof@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 <mchehab@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 $@