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

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

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

$ make texinfodocs
make[1]: ./scripts/sphinx-pre-install: No such file or directory
make[1]: *** [doc/Makefile:73: texinfodocs] Error 127
make: *** [Makefile:2378: texinfodocs] Error 2

@Tom:
Should we add a build step for each of the new targets to
.gitlab-ci.yml and .azure-pipelines.yml?

Best regards

Heinrich

>   	@echo  '  latexdocs       - LaTeX'
>   	@echo  '  pdfdocs         - PDF'
>   	@echo  '  epubdocs        - EPUB'
> diff --git a/doc/media/Makefile b/doc/media/Makefile
> index b9b43a34c3..9b32258696 100644
> --- a/doc/media/Makefile
> +++ b/doc/media/Makefile
> @@ -22,10 +22,11 @@ $(BUILDDIR)/linker_lists.h.rst: ${API}/linker_lists.h ${PARSER} $(SRC_DIR)/linke
>
>   # 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
>
> base-commit: 9bd3d354a1a0712ac27c717df9ad60566b0406ee