* [PATCH] doc: add texinfodocs and infodocs targets
@ 2022-12-17 2:51 Maxim Cournoyer
2022-12-17 13:27 ` Heinrich Schuchardt
0 siblings, 1 reply; 5+ messages in thread
From: Maxim Cournoyer @ 2022-12-17 2:51 UTC (permalink / raw)
To: u-boot
Cc: Maxim Cournoyer, Heinrich Schuchardt, Marek Behún,
Pali Rohár, Quentin Schulz, Simon Glass
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'
@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
--
2.38.1
^ permalink raw reply related [flat|nested] 5+ messages in thread* Re: [PATCH] doc: add texinfodocs and infodocs targets
2022-12-17 2:51 [PATCH] doc: add texinfodocs and infodocs targets Maxim Cournoyer
@ 2022-12-17 13:27 ` Heinrich Schuchardt
2022-12-17 16:02 ` Maxim Cournoyer
2022-12-19 1:53 ` Tom Rini
0 siblings, 2 replies; 5+ messages in thread
From: Heinrich Schuchardt @ 2022-12-17 13:27 UTC (permalink / raw)
To: Maxim Cournoyer, u-boot
Cc: Maxim Cournoyer, Heinrich Schuchardt, Marek Behún,
Pali Rohár, Quentin Schulz, Simon Glass, Tom Rini
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
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [PATCH] doc: add texinfodocs and infodocs targets
2022-12-17 13:27 ` Heinrich Schuchardt
@ 2022-12-17 16:02 ` Maxim Cournoyer
2022-12-17 19:36 ` Heinrich Schuchardt
2022-12-19 1:53 ` Tom Rini
1 sibling, 1 reply; 5+ messages in thread
From: Maxim Cournoyer @ 2022-12-17 16:02 UTC (permalink / raw)
To: Heinrich Schuchardt
Cc: u-boot, Maxim Cournoyer, Marek Behún, Pali Rohár,
Quentin Schulz, Simon Glass, Tom Rini
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] doc: add texinfodocs and infodocs targets
2022-12-17 16:02 ` Maxim Cournoyer
@ 2022-12-17 19:36 ` Heinrich Schuchardt
0 siblings, 0 replies; 5+ messages in thread
From: Heinrich Schuchardt @ 2022-12-17 19:36 UTC (permalink / raw)
To: Maxim Cournoyer
Cc: u-boot, Maxim Cournoyer, Marek Behún, Pali Rohár,
Quentin Schulz, Simon Glass, Tom Rini
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).
>
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] doc: add texinfodocs and infodocs targets
2022-12-17 13:27 ` Heinrich Schuchardt
2022-12-17 16:02 ` Maxim Cournoyer
@ 2022-12-19 1:53 ` Tom Rini
1 sibling, 0 replies; 5+ messages in thread
From: Tom Rini @ 2022-12-19 1:53 UTC (permalink / raw)
To: Heinrich Schuchardt
Cc: Maxim Cournoyer, u-boot, Maxim Cournoyer, Marek Behún,
Pali Rohár, Quentin Schulz, Simon Glass
[-- Attachment #1: Type: text/plain, Size: 2905 bytes --]
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.
--
Tom
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2022-12-19 1:53 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-12-17 2:51 [PATCH] doc: add texinfodocs and infodocs targets Maxim Cournoyer
2022-12-17 13:27 ` Heinrich Schuchardt
2022-12-17 16:02 ` Maxim Cournoyer
2022-12-17 19:36 ` Heinrich Schuchardt
2022-12-19 1:53 ` Tom Rini
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox