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

[Heinrich Schuchardt <xypron.glpk@gmx.de>]

On 12/17/22 16:02, Maxim Cournoyer wrote:
> 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.

make htmldocs is what we rely on to generate
https://u-boot.readthedocs.io. This works fine.

Best regards

Heinrich

>
> 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).
>