doc: add texinfodocs and infodocs targets
Subsystems (3)
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
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
@@ -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
@@ -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
@@ -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
Jonathan Corbet
maintainerQuoted 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).
Signed-off-by Maxim Cournoyer <[email protected]>--- 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
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).
Signed-off-by Maxim Cournoyer <[email protected]>--- 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
PATCH v2 2/2 doc: specify an 'html' build sub-directory for the htmldocs target
In reply to Maxim CournoyerHaving 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
@@ -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
Jonathan Corbet
maintainerRe: [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.
Signed-off-by Maxim Cournoyer <[email protected]>--- Documentation/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/Makefile +0
-0
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
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.
Signed-off-by Maxim Cournoyer <[email protected]>--- Documentation/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/Makefile +0
-0@@ -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
-1htmldocs: @$(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
Jonathan Corbet
maintainerRe: [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
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
Jonathan Corbet
maintainerRe: [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