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

[Maxim Cournoyer <maxim.cournoyer@gmail.com>]

Hi Heinrich,

Heinrich Schuchardt <xypron.glpk@gmx.de> writes:

> On 12/17/22 02:51, Maxim Cournoyer wrote:
>> 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 is basically the same as
>> 1f050e904dd6f2955eecbd22031d912ccb2e7683, which was recently applied
>> to the Linux kernel.
>>
>> Signed-off-by: Maxim Cournoyer <maxim.cournoyer@savoirfairelinux.com>
>> ---
>>
>>   Makefile           |  2 +-
>>   doc/Makefile       | 11 +++++++++++
>>   doc/media/Makefile |  3 ++-
>>   3 files changed, 14 insertions(+), 2 deletions(-)
>>
>> diff --git a/Makefile b/Makefile
>> index de5746399a..597a8886c3 100644
>> --- a/Makefile
>> +++ b/Makefile
>> @@ -2372,7 +2372,7 @@ tcheck:
>>   # Documentation targets
>>   # ---------------------------------------------------------------------------
>>   DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
>> -	       linkcheckdocs dochelp refcheckdocs
>> +	       linkcheckdocs dochelp refcheckdocs texinfodocs infodocs
>>   PHONY += $(DOC_TARGETS)
>>   $(DOC_TARGETS): scripts_basic FORCE
>>   	$(Q)$(MAKE) $(build)=doc $@
>> diff --git a/doc/Makefile b/doc/Makefile
>> index f5de65e927..62effd0fec 100644
>> --- a/doc/Makefile
>> +++ b/doc/Makefile
>> @@ -69,6 +69,15 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
>>   htmldocs:
>>   	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(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 defined above.
>> +infodocs: texinfodocs
>> +	$(MAKE) -C $(BUILDDIR)/texinfo info
>> +
>>   linkcheckdocs:
>>   	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
>>
>> @@ -109,6 +118,8 @@ cleandocs:
>>   dochelp:
>>   	@echo  ' U-Boot documentation in different formats from ReST:'
>>   	@echo  '  htmldocs        - HTML'
>> +	@echo  '  texinfodocs     - Texinfo'
>> +	@echo  '  infodocs        - Info'
>
> This does not work:
>
> $ make infodocs
> make[1]: ./scripts/sphinx-pre-install: No such file or directory

Good catch; this is not a problem introduced by the new targets, I think
(already in the Makefile -- it must happen for other documentation
targets too, no?).  I'll look into it.

The reason I overlooked this was that I'm already patching out the
'sphinx-pre-install' script invocation in the to-become
'u-boot-documentation' Guix package, as that was problematic in the
Linux tree, which uses the same build system (I forgot why exactly,
perhaps it used sudo or wanted to setup its own virtualenvs).

-- 
Thanks,
Maxim