[PATCH 0/3] doc-rst: generic way to build PDF of sub-folder

[PATCH 0/3] doc-rst: generic way to build PDF of sub-folder

[Markus Heiser]

From: Markus Heiser <markus.heiser@darmarIT.de>

Hi Mauro,

here is a small patch series which extends the method to build only sub-folders
to the targets "latexdocs" and "pdfdocs".

If you think, that the two first patches works for you, path them with your next
merge to Jon's doc-next.

The last patch in this series is just for you. It is a small example to
illustrate how we can build small books and link them with intersphinx.

-- Markus --

Markus Heiser (3):
  doc-rst: generic way to build PDF of sub-folders
  doc-rst: define PDF's of the media folder
  doc-rst:media: build separated PDF books (experimental)

 Documentation/Makefile.sphinx |  4 ++--
 Documentation/media/conf.py   | 20 ++++++++++++++++++++
 2 files changed, 22 insertions(+), 2 deletions(-)

-- 
2.7.4

[PATCH 1/3] doc-rst: generic way to build PDF of sub-folders

[Markus Heiser]

From: Markus Heiser <markus.heiser@darmarIT.de>

This extends the method to build only sub-folders to the targets
"latexdocs" and "pdfdocs". To do so, a conf.py in the sub-folder is
required, where the latex_documents of the sub-folder are
defined. E.g. to build only gpu's PDF add the following to the
Documentation/gpu/conf.py::

  +latex_documents = [
  +    ("index", "gpu.tex", "Linux GPU Driver Developer's Guide",
  +     "The kernel development community", "manual"),
  +]

and run:

  make SPHINXDIRS=gpu pdfdocs

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
---
 Documentation/Makefile.sphinx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index 894cfaa..92deea3 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -71,12 +71,12 @@ ifeq ($(HAVE_PDFLATEX),0)
 	$(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
 	@echo "  SKIP    Sphinx $@ target."
 else # HAVE_PDFLATEX
-	@$(call loop_cmd,sphinx,latex,.,latex,.)
+	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
 endif # HAVE_PDFLATEX
 
 pdfdocs: latexdocs
 ifneq ($(HAVE_PDFLATEX),0)
-	$(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/latex
+	$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex)
 endif # HAVE_PDFLATEX
 
 epubdocs:
-- 
2.7.4

[PATCH 2/3] doc-rst: define PDF's of the media folder

[Markus Heiser]

From: Markus Heiser <markus.heiser@darmarIT.de>

To build only the PDF of the media folder run::

  make SPHINXDIRS=media pdfdocs

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
---
 Documentation/media/conf.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/media/conf.py b/Documentation/media/conf.py
index 77cb2bb..bef927b 100644
--- a/Documentation/media/conf.py
+++ b/Documentation/media/conf.py
@@ -3,3 +3,8 @@
 project = 'Linux Media Subsystem Documentation'
 
 tags.add("subproject")
+
+latex_documents = [
+    ('index', 'media.tex', 'Linux Media Subsystem Documentation',
+     'The kernel development community', 'manual'),
+]
-- 
2.7.4

[PATCH 3/3] doc-rst:media: build separated PDF books (experimental)

[Markus Heiser]

From: Markus Heiser <markus.heiser@darmarIT.de>

This patch is only to demonstrate, how to build separated PDF books of
the media sub-folder and close open links with intersphinx.

It is an experimental state (I detected an build error, which I have not
yet traced deep).

Builds PDFs of:

* media_uapi.pdf:  Linux Media Infrastructure userspace API
* media_kapi.pdf:  Media subsystem kernel internal API
* dvb_drivers.pdf: Linux Digital TV driver-specific documentation
* v4l_drivers.pdf: Video4Linux (V4L) driver-specific documentation

It uses the intersphinx extension to close links which refer to content
outside of the (small) pdf-book. The intersphinx links refer to the
documentation served at url:

  https://www.linuxtv.org/downloads/v4l-dvb-apis-new/

E.g.: on page 154 of the media_kapi.pdf in paragraph """YUV Formats
lists existing packed ...""" the 'YUV Formats' text refer to url:

  https://www.linuxtv.org/downloads/v4l-dvb-apis-new/media/uapi/v4l/subdev-formats.html#v4l2-mbus-pixelcode-yuv8

This is only a small example to illustrate how we can build small books
and link them with intersphinx.

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
---
 Documentation/media/conf.py | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/Documentation/media/conf.py b/Documentation/media/conf.py
index bef927b..84575de 100644
--- a/Documentation/media/conf.py
+++ b/Documentation/media/conf.py
@@ -5,6 +5,21 @@ project = 'Linux Media Subsystem Documentation'
 tags.add("subproject")
 
 latex_documents = [
-    ('index', 'media.tex', 'Linux Media Subsystem Documentation',
+    ('media_uapi', 'media_uapi.tex', 'Linux Media Infrastructure userspace API',
+     'The kernel development community', 'manual'),
+    ('media_kapi', 'media_kapi.tex', 'Media subsystem kernel internal API',
+     'The kernel development community', 'manual'),
+    ('dvb-drivers/index', 'dvb_drivers.tex', 'Linux Digital TV driver-specific documentation',
+     'The kernel development community', 'manual'),
+    ('v4l-drivers/index', 'v4l_drivers.tex', 'Video4Linux (V4L) driver-specific documentation',
      'The kernel development community', 'manual'),
 ]
+
+# Since intersphinx is not activated in the global Documentation/conf.py we
+# activate it here. If times comes where it is activated in the global conf.py,
+# we may have to drop these two lines.
+extensions.append('sphinx.ext.intersphinx')
+intersphinx_mapping = {}
+
+# add intersphinx inventory of the *complete* documentation from linuxtv.org
+intersphinx_mapping['media'] = ('https://www.linuxtv.org/downloads/v4l-dvb-apis-new/', None)
-- 
2.7.4

Re: [PATCH 0/3] doc-rst: generic way to build PDF of sub-folder

[Mauro Carvalho Chehab]

Hi Markus,

Em Wed, 24 Aug 2016 17:36:13 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> From: Markus Heiser <markus.heiser@darmarIT.de>
> 
> Hi Mauro,
> 
> here is a small patch series which extends the method to build only sub-folders
> to the targets "latexdocs" and "pdfdocs".
> 
> If you think, that the two first patches works for you, path them with your next
> merge to Jon's doc-next.
> 
> The last patch in this series is just for you. It is a small example to
> illustrate how we can build small books and link them with intersphinx.

Didn't actually review the patches (I'm about to take a short trip).
Just tested the results of those 3 patches. 

It worked. However, I saw two issues there:

1) Now, the documentation, when using SPHINXDIRS=media is not output
at the Documentation/output/latex anymore, but, instead it created a
Documentation/output/media/latex and wrote the books there.

2) If built without SPHINXDIRS, it is producing just one document and
storing it at Documentation/output. I would expect it to do the same
on both cases.

Btw, I'm planning to split the media documentation on 4 books even when
building without SPHINXDIRS. There are two reasons for that:

1) the uAPI book has a different licence than the other books;

2) the uAPI book should be split into 5 parts, and each part should
reset the chapter numberation to 1, in order to produce the same
chapter numbering as the HTML book.

>From what I saw, the control if LaTeX will use parts/chapter/section
or just chapter section is controlled per conf.py file. It means that
we'll need to have a separate conf.py for the uAPI book - or to have
an Sphinx extension that would allow adjusting the LaTeX layout via
some meta-tags at the book's index.rst.

Regards,
Mauro

Re: [PATCH 0/3] doc-rst: generic way to build PDF of sub-folder

[Markus Heiser]

Am 26.08.2016 um 13:34 schrieb Mauro Carvalho Chehab <mchehab@infradead.org>:

> Hi Markus,
> 
> Em Wed, 24 Aug 2016 17:36:13 +0200
> Markus Heiser <markus.heiser@darmarit.de> escreveu:
> 
>> From: Markus Heiser <markus.heiser@darmarIT.de>
>> 
>> Hi Mauro,
>> 
>> here is a small patch series which extends the method to build only sub-folders
>> to the targets "latexdocs" and "pdfdocs".
>> 
>> If you think, that the two first patches works for you, path them with your next
>> merge to Jon's doc-next.
>> 
>> The last patch in this series is just for you. It is a small example to
>> illustrate how we can build small books and link them with intersphinx.
> 
> Didn't actually review the patches (I'm about to take a short trip).
> Just tested the results of those 3 patches. 
> 
> It worked. However, I saw two issues there:
> 
> 1) Now, the documentation, when using SPHINXDIRS=media is not output
> at the Documentation/output/latex anymore, but, instead it created a
> Documentation/output/media/latex and wrote the books there.

Yes, we have not finished the discussion where all these outputs should
take place:

  https://www.mail-archive.com/linux-media@vger.kernel.org/msg101572.html

ATM all sub-folder builds are placed in:

  Documentation/output/{sub-folder-name}

If someone has a proper solution, he can patch the make file.


> 2) If built without SPHINXDIRS, it is producing just one document and
> storing it at Documentation/output. I would expect it to do the same
> on both cases.

IMHO not .. I haven't change anything in the Documentation/conf.py

It is very simple: with SPHINXDIR, the latex_documents settings
from subdir's conf.py is used. Without, the ones from 
Documentation/conf.py is used.


> Btw, I'm planning to split the media documentation on 4 books even when
> building without SPHINXDIRS. There are two reasons for that:
> 
> 1) the uAPI book has a different licence than the other books;
> 
> 2) the uAPI book should be split into 5 parts, and each part should
> reset the chapter numberation to 1, in order to produce the same
> chapter numbering as the HTML book.
> 
> From what I saw, the control if LaTeX will use parts/chapter/section
> or just chapter section is controlled per conf.py file. It means that
> we'll need to have a separate conf.py for the uAPI book - or to have
> an Sphinx extension that would allow adjusting the LaTeX layout via
> some meta-tags at the book's index.rst.

Yes, top-level sectioning is for all latex_documents the same:

* http://www.sphinx-doc.org/en/stable/config.html#confval-latex_toplevel_sectioning

If you really need per-document top-level sectioning, we will find a solution.

-- Markus --

> 
> Regards,
> Mauro

Re: [PATCH 0/3] doc-rst: generic way to build PDF of sub-folder

[Jonathan Corbet]

On Wed, 24 Aug 2016 17:36:13 +0200
Markus Heiser <markus.heiser@darmarit.de> wrote:

> here is a small patch series which extends the method to build only sub-folders
> to the targets "latexdocs" and "pdfdocs".

Well this doesn't seem to break anything, so I went ahead and applied
it :)

Thanks,

jon

Re: [PATCH 0/3] doc-rst: generic way to build PDF of sub-folder

[Jonathan Corbet]

On Thu, 1 Sep 2016 08:53:34 -0600
Jonathan Corbet <corbet@lwn.net> wrote:

> > here is a small patch series which extends the method to build only sub-folders
> > to the targets "latexdocs" and "pdfdocs".  
> 
> Well this doesn't seem to break anything, so I went ahead and applied
> it :)

By that I mean I applied the first two, of course; I left the
media-specific one for Mauro.

jon

Re: [PATCH 1/3] doc-rst: generic way to build PDF of sub-folders

[Jani Nikula]

On Wed, 24 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> From: Markus Heiser <markus.heiser@darmarIT.de>
>
> This extends the method to build only sub-folders to the targets
> "latexdocs" and "pdfdocs". To do so, a conf.py in the sub-folder is
> required, where the latex_documents of the sub-folder are
> defined. E.g. to build only gpu's PDF add the following to the
> Documentation/gpu/conf.py::
>
>   +latex_documents = [
>   +    ("index", "gpu.tex", "Linux GPU Driver Developer's Guide",
>   +     "The kernel development community", "manual"),
>   +]
>
> and run:
>
>   make SPHINXDIRS=gpu pdfdocs

Did you ever try this with more than one subfolder?

BR,
Jani.

>
> Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
> ---
>  Documentation/Makefile.sphinx | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
> index 894cfaa..92deea3 100644
> --- a/Documentation/Makefile.sphinx
> +++ b/Documentation/Makefile.sphinx
> @@ -71,12 +71,12 @@ ifeq ($(HAVE_PDFLATEX),0)
>  	$(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
>  	@echo "  SKIP    Sphinx $@ target."
>  else # HAVE_PDFLATEX
> -	@$(call loop_cmd,sphinx,latex,.,latex,.)
> +	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
>  endif # HAVE_PDFLATEX
>  
>  pdfdocs: latexdocs
>  ifneq ($(HAVE_PDFLATEX),0)
> -	$(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/latex
> +	$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex)
>  endif # HAVE_PDFLATEX
>  
>  epubdocs:

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH 1/3] doc-rst: generic way to build PDF of sub-folders

[Markus Heiser]

Am 02.11.2016 um 12:43 schrieb Jani Nikula <jani.nikula@intel.com>:

> On Wed, 24 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
>> From: Markus Heiser <markus.heiser@darmarIT.de>
>> 
>> This extends the method to build only sub-folders to the targets
>> "latexdocs" and "pdfdocs". To do so, a conf.py in the sub-folder is
>> required, where the latex_documents of the sub-folder are
>> defined. E.g. to build only gpu's PDF add the following to the
>> Documentation/gpu/conf.py::
>> 
>>  +latex_documents = [
>>  +    ("index", "gpu.tex", "Linux GPU Driver Developer's Guide",
>>  +     "The kernel development community", "manual"),
>>  +]
>> 
>> and run:
>> 
>>  make SPHINXDIRS=gpu pdfdocs
> 
> Did you ever try this with more than one subfolder?

Seems not, there is a ";" missed in the 'foreach' loop, see patch
below.

To avoid conflicts, can you apply the ";" on your 
"Makefile.sphinx improvements" series? / Thanks

diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index 92deea3..b7fbd12 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -76,7 +76,7 @@ endif # HAVE_PDFLATEX
 
 pdfdocs: latexdocs
 ifneq ($(HAVE_PDFLATEX),0)
-       $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex)
+       $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex;)
 endif # HAVE_PDFLATEX
 
 epubdocs:


--Markus --

Re: [PATCH 1/3] doc-rst: generic way to build PDF of sub-folders

[Jani Nikula]

On Wed, 02 Nov 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Am 02.11.2016 um 12:43 schrieb Jani Nikula <jani.nikula@intel.com>:
>
>> On Wed, 24 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
>>> From: Markus Heiser <markus.heiser@darmarIT.de>
>>> 
>>> This extends the method to build only sub-folders to the targets
>>> "latexdocs" and "pdfdocs". To do so, a conf.py in the sub-folder is
>>> required, where the latex_documents of the sub-folder are
>>> defined. E.g. to build only gpu's PDF add the following to the
>>> Documentation/gpu/conf.py::
>>> 
>>>  +latex_documents = [
>>>  +    ("index", "gpu.tex", "Linux GPU Driver Developer's Guide",
>>>  +     "The kernel development community", "manual"),
>>>  +]
>>> 
>>> and run:
>>> 
>>>  make SPHINXDIRS=gpu pdfdocs
>> 
>> Did you ever try this with more than one subfolder?
>
> Seems not, there is a ";" missed in the 'foreach' loop, see patch
> below.
>
> To avoid conflicts, can you apply the ";" on your 
> "Makefile.sphinx improvements" series? / Thanks

Thanks, done.

http://lkml.kernel.org/r/1478097913-12561-1-git-send-email-jani.nikula@intel.com

>
> diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
> index 92deea3..b7fbd12 100644
> --- a/Documentation/Makefile.sphinx
> +++ b/Documentation/Makefile.sphinx
> @@ -76,7 +76,7 @@ endif # HAVE_PDFLATEX
>  
>  pdfdocs: latexdocs
>  ifneq ($(HAVE_PDFLATEX),0)
> -       $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex)
> +       $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex;)
>  endif # HAVE_PDFLATEX
>  
>  epubdocs:
>
>
> --Markus --
>

-- 
Jani Nikula, Intel Open Source Technology Center