Skip to contentSkip to conversation

doc: add texinfodocs and infodocs targets

PATCH Superseded Maxim Cournoyer 2 participants 10 messages Nov 16, 2022 – Nov 28, 2022

Subsystems (3)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

v2 cover doc: add texinfodocs and infodocs targets

Hi,

This is revision 2 of the series, following feedback from Jonathan Corbet. The second commit was split from the first one to ease review/discussion.

Thank you,

Maxim Cournoyer (2):
doc: add texinfodocs and infodocs targets
doc: specify an 'html' build sub-directory for the htmldocs target

 Documentation/Makefile                     | 13 ++++++++++++-
 Documentation/userspace-api/media/Makefile |  3 ++-
 Makefile                                   |  2 +-
 3 files changed, 15 insertions(+), 3 deletions(-)

base-commit: 81e7cfa3a9eb4ba6993a9c71772fdab21bc5d870

Signature · 1 line
2.38.1
#1 lore raw

PATCH v2 1/2 doc: add texinfodocs and infodocs targets

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

---
 Documentation/Makefile                     | 11 +++++++++++
 Documentation/userspace-api/media/Makefile |  3 ++-
 Makefile                                   |  2 +-
 3 files changed, 14 insertions(+), 2 deletions(-)
Documentation/Makefile +11 -0
index 64d44c1ecad3..bb73dcb5ed05 100644
@@ -95,6 +95,15 @@ htmldocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
 	@+$(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 define above.
+infodocs: texinfodocs
+	$(MAKE) -C $(BUILDDIR)/texinfo info
+
 linkcheckdocs:
 	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
 
@@ -143,6 +152,8 @@ cleandocs:
 dochelp:
 	@echo  ' Linux kernel internal documentation in different formats from ReST:'
 	@echo  '  htmldocs        - HTML'
+	@echo  '  texinfodocs     - Texinfo'
+	@echo  '  infodocs        - Info'
 	@echo  '  latexdocs       - LaTeX'
 	@echo  '  pdfdocs         - PDF'
 	@echo  '  epubdocs        - EPUB'
Documentation/userspace-api/media/Makefile +2 -1
index 00922aa7efde..3d8aaf5c253b 100644
@@ -47,10 +47,11 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception
 
 # 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
Makefile +1 -1
index 58cd4f5e1c3a..b3266c408b6c 100644
@@ -1785,7 +1785,7 @@ $(help-board-dirs): help-%:
 # Documentation targets
 # ---------------------------------------------------------------------------
 DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
-	       linkcheckdocs dochelp refcheckdocs
+	       linkcheckdocs dochelp refcheckdocs texinfodocs infodocs
 PHONY += $(DOC_TARGETS)
 $(DOC_TARGETS):
 	$(Q)$(MAKE) $(build)=Documentation $@
Signature · 1 line
2.38.1
maintainer
#2 lore raw
Quoted 10 lines · Maxim Cournoyer

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

---
 Documentation/Makefile                     | 11 +++++++++++
 Documentation/userspace-api/media/Makefile |  3 ++-
 Makefile                                   |  2 +-
 3 files changed, 14 insertions(+), 2 deletions(-)

Wow, I thought that HTML output from Sphinx was slow, but texinfo is another thing altogether...

Oh well, I guess for some folks it's worth waiting for, so I've applied this patch, thanks.

jon

#3 lore raw

Hi Jonathan,

Quoted 13 lines · Jonathan Corbet
Quoted 10 lines · Maxim Cournoyer

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

---
 Documentation/Makefile                     | 11 +++++++++++
 Documentation/userspace-api/media/Makefile |  3 ++-
 Makefile                                   |  2 +-
 3 files changed, 14 insertions(+), 2 deletions(-)
Quoted 2 lines

Wow, I thought that HTML output from Sphinx was slow, but texinfo is another thing altogether...

Are their timing really that much different? Since the .doctrees is reused, I'd expect the first target to take the most time, the second one somewhat less. In my case, I build HTML first and info after, and I *think* info takes less time, although still takes too long to my taste. Sadly, setting SPHINXOPTS=jN to attempt some parallelization doesn't help any.

Quoted 2 lines

Oh well, I guess for some folks it's worth waiting for, so I've applied this patch, thanks.n

Thank you!

Signature · 1 line
Maxim
#4 lore raw

PATCH v2 2/2 doc: specify an 'html' build sub-directory for the htmldocs target

In reply to Maxim Cournoyer

Having the generated HTML documentation under its own output sub-directory makes it easier to install, since it's clean from .doctrees or other output formats.

---
 Documentation/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/Makefile +1 -1
index bb73dcb5ed05..bd8dac560633 100644
@@ -93,7 +93,7 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
 
 htmldocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
-	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
+	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),html,$(var)))
 
 texinfodocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
Signature · 1 line
2.38.1
maintainer
#5 lore raw

Re: [PATCH v2 2/2] doc: specify an 'html' build sub-directory for the htmldocs target

Quoted 14 lines · Maxim Cournoyer

Having the generated HTML documentation under its own output sub-directory makes it easier to install, since it's clean from .doctrees or other output formats.

---
 Documentation/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/Makefile +0 -0
index bb73dcb5ed05..bd8dac560633 100644

Documentation/Makefile quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) · line 96

Quoted 5 lines
Documentation/Makefile +1 -1
@@ -93,7 +93,7 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
 
 htmldocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
-	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
+	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),html,$(var)))

I think I'm going to hold off on this one. As I said before, it would have made sense to do things this way when we made the transition. At this point, though, I think the potential for trouble outweighs the benefits that would come from moving things around in this way.

Thanks,

jon

#6 lore raw

Re: [PATCH v2 2/2] doc: specify an 'html' build sub-directory for the htmldocs target

Hi Jonathan,

Quoted 17 lines · Jonathan Corbet
Quoted 15 lines · Maxim Cournoyer

Having the generated HTML documentation under its own output sub-directory makes it easier to install, since it's clean from .doctrees or other output formats.

---
 Documentation/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/Makefile +0 -0
index bb73dcb5ed05..bd8dac560633 100644
@@ -93,7 +93,7 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
 
Quoted 9 lines

Documentation/Makefile quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) · line 96

Quoted 4 lines
Documentation/Makefile +1 -1
 htmldocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
-	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
+	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),html,$(var)))

I think I'm going to hold off on this one. As I said before, it would have made sense to do things this way when we made the transition. At this point, though, I think the potential for trouble outweighs the benefits that would come from moving things around in this way.

OK. The potential for troubles would lie with the scripts to deploy the doc to the web site, I'd guess? If that's the place we'd expect problems, I'm happy to be pointed to it and can try adjusting the scripts for the change.

Otherwise, I can keep applying this small patch locally to my build, as it makes it much easier to cleanly install both the HTML and info target outputs when packaging the kernel and its documentation.

Signature · 2 lines
Thanks,
Maxim
maintainer
#7 lore raw

Re: [PATCH v2 2/2] doc: specify an 'html' build sub-directory for the htmldocs target

Quoted 8 lines · Maxim Cournoyer

Hi Jonathan,

Quoted 4 lines · Jonathan Corbet

I think I'm going to hold off on this one. As I said before, it would have made sense to do things this way when we made the transition. At this point, though, I think the potential for trouble outweighs the benefits that would come from moving things around in this way.

Quoted 4 lines

OK. The potential for troubles would lie with the scripts to deploy the doc to the web site, I'd guess? If that's the place we'd expect problems, I'm happy to be pointed to it and can try adjusting the scripts for the change.

The trouble lies in any number of scripts at any number of sites; calling this an ABI change would be a stretch, but some of the same concerns apply.

Getting the docs build on kernel.org updated would not be a huge problem, I think, but I don't know what else might break.

We can reconsider this, but not before the merge window.

Thanks,

jon

#8 lore raw

Re: [PATCH v2 2/2] doc: specify an 'html' build sub-directory for the htmldocs target

Hi,

Quoted 10 lines · Jonathan Corbet
Quoted 8 lines · Maxim Cournoyer

Hi Jonathan,

Quoted 4 lines · Jonathan Corbet

I think I'm going to hold off on this one. As I said before, it would have made sense to do things this way when we made the transition. At this point, though, I think the potential for trouble outweighs the benefits that would come from moving things around in this way.

Quoted 8 lines
Quoted 4 lines

OK. The potential for troubles would lie with the scripts to deploy the doc to the web site, I'd guess? If that's the place we'd expect problems, I'm happy to be pointed to it and can try adjusting the scripts for the change.

The trouble lies in any number of scripts at any number of sites; calling this an ABI change would be a stretch, but some of the same concerns apply.

Right. I wouldn't be too concerned with sites other than the main Linux documentation site, though?

Quoted 4 lines

Getting the docs build on kernel.org updated would not be a huge problem, I think, but I don't know what else might break.

We can reconsider this, but not before the merge window.

Understood. Thanks for the follow up! Should I resend when the next window opens?

Signature · 2 lines
Thanks,
Maxim
maintainer
#9 lore raw

Re: [PATCH v2 2/2] doc: specify an 'html' build sub-directory for the htmldocs target

Quoted 19 lines · Maxim Cournoyer

Hi,

Quoted 15 lines · Jonathan Corbet
Quoted 12 lines · Maxim Cournoyer

Hi Jonathan,

Quoted 4 lines · Jonathan Corbet

I think I'm going to hold off on this one. As I said before, it would have made sense to do things this way when we made the transition. At this point, though, I think the potential for trouble outweighs the benefits that would come from moving things around in this way.

OK. The potential for troubles would lie with the scripts to deploy the doc to the web site, I'd guess? If that's the place we'd expect problems, I'm happy to be pointed to it and can try adjusting the scripts for the change.

Quoted 6 lines
Quoted 3 lines

The trouble lies in any number of scripts at any number of sites; calling this an ABI change would be a stretch, but some of the same concerns apply.

Right. I wouldn't be too concerned with sites other than the main Linux documentation site, though?

We can't really take that attitude; breaking users is bad. There may (or may not) be any number of companies generating the HTML docs for internal use, for example; breaking them would be rude at best.

Quoted 7 lines
Quoted 4 lines

Getting the docs build on kernel.org updated would not be a huge problem, I think, but I don't know what else might break.

We can reconsider this, but not before the merge window.

Understood. Thanks for the follow up! Should I resend when the next window opens?

Sure, you can do that. No guarantees that the benefits of the change will seem worth the risk at that time, though.

Thanks,

jon