diff mbox series

doc: add texinfodocs and infodocs targets

Message ID 20221217025137.2514-1-maxim.cournoyer@savoirfairelinux.com
State Superseded
Delegated to: Heinrich Schuchardt
Headers show
Series doc: add texinfodocs and infodocs targets | expand

Commit Message

Maxim Cournoyer Dec. 17, 2022, 2:51 a.m. UTC 
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(-)


base-commit: 9bd3d354a1a0712ac27c717df9ad60566b0406ee

Comments

Heinrich Schuchardt Dec. 17, 2022, 1:27 p.m. UTC | #1 
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
Maxim Cournoyer Dec. 17, 2022, 4:02 p.m. UTC | #2 
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).
Heinrich Schuchardt Dec. 17, 2022, 7:36 p.m. UTC | #3 
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).
>
Tom Rini Dec. 19, 2022, 1:53 a.m. UTC | #4 
On Sat, Dec 17, 2022 at 01:27:52PM +0000, Heinrich Schuchardt wrote:
> 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?

We should rename the job and build all doc targets, once they've been
fixed I think.
diff mbox series

Patch

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'
 	@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