[PATCH v2 0/2] doc: add texinfodocs and infodocs targets

[PATCH v2 0/2] doc: add texinfodocs and infodocs targets

[Maxim Cournoyer]

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
-- 
2.38.1

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

[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 <maxim.cournoyer@gmail.com>
---
 Documentation/Makefile                     | 11 +++++++++++
 Documentation/userspace-api/media/Makefile |  3 ++-
 Makefile                                   |  2 +-
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 64d44c1ecad3..bb73dcb5ed05 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -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'
diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile
index 00922aa7efde..3d8aaf5c253b 100644
--- a/Documentation/userspace-api/media/Makefile
+++ b/Documentation/userspace-api/media/Makefile
@@ -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
diff --git a/Makefile b/Makefile
index 58cd4f5e1c3a..b3266c408b6c 100644
--- a/Makefile
+++ b/Makefile
@@ -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 $@
-- 
2.38.1

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

[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 <maxim.cournoyer@gmail.com>
---
 Documentation/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index bb73dcb5ed05..bd8dac560633 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -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
-- 
2.38.1

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

[Jonathan Corbet]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> 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 <maxim.cournoyer@gmail.com>
> ---
>  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

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

[Jonathan Corbet]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> 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 <maxim.cournoyer@gmail.com>
> ---
>  Documentation/Makefile | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index bb73dcb5ed05..bd8dac560633 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -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 1/2] doc: add texinfodocs and infodocs targets

[Maxim Cournoyer]

Hi Jonathan,

Jonathan Corbet <corbet@lwn.net> writes:

> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>
>> 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 <maxim.cournoyer@gmail.com>
>> ---
>>  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...

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.

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

Thank you!

-- 
Maxim

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

[Maxim Cournoyer]

Hi Jonathan,

Jonathan Corbet <corbet@lwn.net> writes:

> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>
>> 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 <maxim.cournoyer@gmail.com>
>> ---
>>  Documentation/Makefile | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/Makefile b/Documentation/Makefile
>> index bb73dcb5ed05..bd8dac560633 100644
>> --- a/Documentation/Makefile
>> +++ b/Documentation/Makefile
>> @@ -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.

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.

-- 
Thanks,
Maxim

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

[Jonathan Corbet]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Hi Jonathan,
>
> Jonathan Corbet <corbet@lwn.net> writes:
>> 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.

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

[Maxim Cournoyer]

Hi,

Jonathan Corbet <corbet@lwn.net> writes:

> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>
>> Hi Jonathan,
>>
>> Jonathan Corbet <corbet@lwn.net> writes:
>>> 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.
>
> 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?

> 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?

-- 
Thanks,
Maxim

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

[Jonathan Corbet]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Hi,
>
> Jonathan Corbet <corbet@lwn.net> writes:
>
>> Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>>
>>> Hi Jonathan,
>>>
>>> Jonathan Corbet <corbet@lwn.net> writes:
>>>> 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.
>>
>> 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.

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