[PATCH] doc: add texinfodocs and infodocs targets

[PATCH] doc: add texinfodocs and infodocs targets

[Maxim Cournoyer]

Sphinx supports generating Texinfo sources and Info documentation,
which can be navigated easily and is convenient to search (via the
indexed nodes or anchors, for example).

This change also causes the html output to appear under its own output
sub-directory, which makes it easier to install, since it's clean from
.doctrees or other output formats.

Signed-off-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
---
 Documentation/Makefile                     | 13 ++++++++++++-
 Documentation/userspace-api/media/Makefile |  3 ++-
 Makefile                                   |  2 +-
 3 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 64d44c1ecad3..bd8dac560633 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -93,7 +93,16 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
 
 htmldocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
-	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
+	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),html,$(var)))
+
+texinfodocs:
+	@$(srctree)/scripts/sphinx-pre-install --version-check
+	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var)))
+
+# Note: the 'info' Make target is generated by sphinx itself when
+# running the texinfodocs target define above.
+infodocs: texinfodocs
+	$(MAKE) -C $(BUILDDIR)/texinfo info
 
 linkcheckdocs:
 	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
@@ -143,6 +152,8 @@ cleandocs:
 dochelp:
 	@echo  ' Linux kernel internal documentation in different formats from ReST:'
 	@echo  '  htmldocs        - HTML'
+	@echo  '  texinfodocs     - Texinfo'
+	@echo  '  infodocs        - Info'
 	@echo  '  latexdocs       - LaTeX'
 	@echo  '  pdfdocs         - PDF'
 	@echo  '  epubdocs        - EPUB'
diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile
index 00922aa7efde..3d8aaf5c253b 100644
--- a/Documentation/userspace-api/media/Makefile
+++ b/Documentation/userspace-api/media/Makefile
@@ -47,10 +47,11 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception
 
 # Media build rules
 
-.PHONY: all html epub xml latex
+.PHONY: all html texinfo epub xml latex
 
 all: $(IMGDOT) $(BUILDDIR) ${TARGETS}
 html: all
+texinfo: all
 epub: all
 xml: all
 latex: $(IMGPDF) all
diff --git a/Makefile b/Makefile
index 58cd4f5e1c3a..b3266c408b6c 100644
--- a/Makefile
+++ b/Makefile
@@ -1785,7 +1785,7 @@ $(help-board-dirs): help-%:
 # Documentation targets
 # ---------------------------------------------------------------------------
 DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
-	       linkcheckdocs dochelp refcheckdocs
+	       linkcheckdocs dochelp refcheckdocs texinfodocs infodocs
 PHONY += $(DOC_TARGETS)
 $(DOC_TARGETS):
 	$(Q)$(MAKE) $(build)=Documentation $@

base-commit: 81e7cfa3a9eb4ba6993a9c71772fdab21bc5d870
-- 
2.38.1

Re: [PATCH] doc: add texinfodocs and infodocs targets

[Jonathan Corbet]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Sphinx supports generating Texinfo sources and Info documentation,
> which can be navigated easily and is convenient to search (via the
> indexed nodes or anchors, for example).

Can you tell me a bit more about the use case for this?  Nobody has
asked for it so far...  I'm not really opposed to adding it, but it
would be nice to know why.

> This change also causes the html output to appear under its own output
> sub-directory, which makes it easier to install, since it's clean from
> .doctrees or other output formats.

"This change also ... " is a red flag saying that you should have split
it into a separate patch.

That change may be a bit harder to accept, since it's a behavioral
change that will certainly annoy some people.  At a minimum, it would
have to be coordinated with the automated docs builds at kernel.org.
One could certainly make the case that we should have done things this
way from the beginning; I'm a bit reluctant to change it now.

Thanks,

jon

Re: [PATCH] doc: add texinfodocs and infodocs targets

[Maxim Cournoyer]

Hi Jonathan,

Thank you for the quick reply.

Jonathan Corbet <corbet@lwn.net> writes:

> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>
>> Sphinx supports generating Texinfo sources and Info documentation,
>> which can be navigated easily and is convenient to search (via the
>> indexed nodes or anchors, for example).

> Can you tell me a bit more about the use case for this?  Nobody has
> asked for it so far...  I'm not really opposed to adding it, but it
> would be nice to know why.

I didn't know about Texinfo much at all until I started using Guix
System, where is it used extensively as the main documentation system.
Since then I've grown to appreciate it, even favor it most of the time,
to HTML docs due to it being usable offline even when only a terminal
emulator is available, and matching the version of the software
installed.  In contrast with man pages, which are typically very flat,
info manual can be organized into sections that are rendered into menus
that can be navigated using just a keyboard.  Another point is size.
The compressed TheLinuxKernel.info.gz info documentation weighs 12 MiB
on disk, compared to 183 MiB for the HTML version.

In short, Texinfo gives you the organization/navigability of HTML in a
format that can be used anywhere, even on headless servers.  When the
document is well indexed, it's even faster than HTML at helping you find
something, via e.g.:

$ info TheLinuxKernel i rcu_ TAB
--8<---------------cut here---------------start------------->8---
40 completions:
rcu_access_pointer (C macro)               rcu_pointer_handoff (C macro)
rcu_assign_pointer (C macro)               RCU_POINTER_INITIALIZER (C macro)
rcu_barrier (C function)                   rcu_read_lock (C function)
rcu_dereference (C macro)                  rcu_read_lock_bh (C function)
rcu_dereference_bh (C macro)               rcu_read_lock_bh_held (C function)
rcu_dereference_bh_check (C macro)         rcu_read_lock_held (C function)
rcu_dereference_check (C macro)            rcu_read_lock_held_common (C function)
rcu_dereference_protected (C macro)        rcu_read_lock_sched (C function)
rcu_dereference_sched (C macro)            rcu_read_unlock (C function)
rcu_dereference_sched_check (C macro)      rcu_read_unlock_bh (C function)
rcu_expedite_gp (C function)               rcu_read_unlock_sched (C function)
rcu_head_after_call_rcu (C function)       rcu_replace_pointer (C macro)
rcu_head_init (C function)                 rcu_sync_dtor (C function)
RCU_INIT_POINTER (C macro)                 rcu_sync_enter (C function)
RCU_INITIALIZER (C macro)                  rcu_sync_enter_start (C function)
rcu_irq_exit_check_preempt (C function)    rcu_sync_exit (C function)
rcu_is_cpu_rrupt_from_idle (C function)    rcu_sync_func (C function)
rcu_is_watching (C function)               rcu_sync_init (C function)
RCU_LOCKDEP_WARN (C macro)                 rcu_sync_is_idle (C function)
RCU_NONIDLE (C macro)                      rcu_unexpedite_gp (C function)
--8<---------------cut here---------------end--------------->8---

rcu_barr TAB -> rcu_barrier (C function)
--8<---------------cut here---------------start------------->8---

 -- Function: void rcu_barrier (void)

     Wait until all in-flight *note call_rcu(): 4188. callbacks
     complete.

‘Parameters’

‘void’

     no arguments

‘Description’
[...]
--8<---------------cut here---------------end--------------->8---

Unfortunately only the kernel API seems to be indexed for now.  I was
trying to find the supported kernel boot parameters, but no index
appeared to be registered for it.  In these cases, one can always
fall-back to plain text search (regexp) via C-s, or navigate the menus
like you would in HTML:

$ info TheLinuxKernel
--8<---------------cut here---------------start------------->8---
* Menu:

* Licensing documentation::
* User-oriented documentation::
* Firmware-related documentation::
* Application-developer documentation::
* Introduction to kernel development::
* Kernel API documentation::
* Architecture-agnostic documentation::
* Architecture-specific documentation::
* Other documentation::
* Translations: Translations<2>.
* Indices and tables::
* Index::
--8<---------------cut here---------------end--------------->8---

Press 2 or m 'User-' TAB' to enter the 2nd section.
--8<---------------cut here---------------start------------->8---
Next: Firmware-related documentation,  Prev: Licensing documentation,  Up: Top

2 User-oriented documentation
*****************************

The following manuals are written for ‘users’ of the kernel — those who
are trying to get it to work optimally on a given system.

* Menu:

* The Linux kernel user’s and administrator’s guide::
* Kernel Build System::

--8<---------------cut here---------------end--------------->8---

Press 1 to select the first entry.
--8<---------------cut here---------------start------------->8---
Next: Kernel Build System,  Up: User-oriented documentation

2.1 The Linux kernel user’s and administrator’s guide
=====================================================

The following is a collection of user-oriented documents that have been

[...]
* Menu:

* GNU Linux-libre <http;//linux-libre.fsfla.org>: GNU Linux-libre <http //linux-libre fsfla org>.
* The kernel’s command-line parameters::
[...]
--8<---------------cut here---------------end--------------->8---

Press 2.  The section "2.1.2 The kernel’s command-line parameters" is
now displayed.

If you know the name of the section and if it doesn't contain funny
characters, you can jump straight to it from the command line, like so:

$ info '(TheLinuxKernel) cpu lists'

Anyway, I hope I was able to demonstrate some of the strengths of
Texinfo with the above.  In case your interest is piqued, 'info info'
has it all.

>> This change also causes the html output to appear under its own
>> output sub-directory, which makes it easier to install, since it's
>> clean from .doctrees or other output formats.
>
> "This change also ... " is a red flag saying that you should have split
> it into a separate patch.
>
> That change may be a bit harder to accept, since it's a behavioral
> change that will certainly annoy some people.  At a minimum, it would
> have to be coordinated with the automated docs builds at kernel.org.
> One could certainly make the case that we should have done things this
> way from the beginning; I'm a bit reluctant to change it now.

I'll split the html prefix change in a v2, and it can be discussed
separately.

-- 
Thanks,
Maxim