[PATCH] docs: Makefile: Add dependency to $(YNL_INDEX) for targets other than htmldocs

[PATCH] docs: Makefile: Add dependency to $(YNL_INDEX) for targets other than htmldocs

[Akira Yokosawa]

Commit f061c9f7d058 ("Documentation: Document each netlink family")
added recipes for YAML -> RST conversion.
Then commit 7da8bdbf8f5d ("docs: Makefile: Fix make cleandocs by
deleting generated .rst files") made sure those converted .rst files
are cleaned by "make cleandocs".

However, they took care of htmldocs build only.

If one of other targets such as latexdocs or epubdocs is built
without building htmldocs, missing .rst files can cause additional
WARNINGs from sphinx-build as follow:

    ./Documentation/userspace-api/netlink/specs.rst:18: WARNING: undefined label: 'specs'
    ./Documentation/userspace-api/netlink/netlink-raw.rst:64: WARNING: unknown document: '../../networking/netlink_spec/rt_link'
    ./Documentation/userspace-api/netlink/netlink-raw.rst:64: WARNING: unknown document: '../../networking/netlink_spec/tc'
    ./Documentation/userspace-api/netlink/index.rst:21: WARNING: undefined label: 'specs'

Add dependency to $(YNL_INDEX) for other targets and allow any targets
to be built cleanly right after "make cleandocs".

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: stable@vger.kernel.org  # v6.7
Cc: Thorsten Blum <thorsten.blum@toblux.com>
Cc: Breno Leitao <leitao@debian.org>
Cc: Jakub Kicinski <kuba@kernel.org>
Cc: David S. Miller <davem@davemloft.net>
---
Hi,

While the first offending commit went through the -net tree, 
I'd like Jon to pick this up provided there is no objection from
Jakub or davem.

I know there are complaints against generating files under the
documentation source tree (thread under [1]). 
So this is a tentative workaround until someone comes up with
a proper way to fix the fundamental issue.

I wouldn't add Fixes tags.  Almost all the people care only of
htmldocs...

[1]: https://lore.kernel.org/linux-doc/874jevjgvo.fsf@intel.com/

        Thanks, Akira
---
 Documentation/Makefile | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 4479910166fc..b68f8c816897 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -111,7 +111,9 @@ $(YNL_INDEX): $(YNL_RST_FILES)
 $(YNL_RST_DIR)/%.rst: $(YNL_YAML_DIR)/%.yaml $(YNL_TOOL)
 	$(Q)$(YNL_TOOL) -i $< -o $@
 
-htmldocs: $(YNL_INDEX)
+htmldocs texinfodocs latexdocs epubdocs xmldocs: $(YNL_INDEX)
+
+htmldocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
 	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
 

base-commit: a800c6f5b0573847722c5ec70e0ce5cde6ca13dd
-- 
2.34.1

Re: [PATCH] docs: Makefile: Add dependency to $(YNL_INDEX) for targets other than htmldocs

[Breno Leitao]

On Tue, Mar 05, 2024 at 01:23:00PM +0900, Akira Yokosawa wrote:
> Commit f061c9f7d058 ("Documentation: Document each netlink family")
> added recipes for YAML -> RST conversion.
> Then commit 7da8bdbf8f5d ("docs: Makefile: Fix make cleandocs by
> deleting generated .rst files") made sure those converted .rst files
> are cleaned by "make cleandocs".
> 
> However, they took care of htmldocs build only.
> 
> If one of other targets such as latexdocs or epubdocs is built
> without building htmldocs, missing .rst files can cause additional
> WARNINGs from sphinx-build as follow:
> 
>     ./Documentation/userspace-api/netlink/specs.rst:18: WARNING: undefined label: 'specs'
>     ./Documentation/userspace-api/netlink/netlink-raw.rst:64: WARNING: unknown document: '../../networking/netlink_spec/rt_link'
>     ./Documentation/userspace-api/netlink/netlink-raw.rst:64: WARNING: unknown document: '../../networking/netlink_spec/tc'
>     ./Documentation/userspace-api/netlink/index.rst:21: WARNING: undefined label: 'specs'
> 
> Add dependency to $(YNL_INDEX) for other targets and allow any targets
> to be built cleanly right after "make cleandocs".
> 
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>

Reviwed-by: Breno Leitao <leitao@debian.org>

Re: [PATCH] docs: Makefile: Add dependency to $(YNL_INDEX) for targets other than htmldocs

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> Commit f061c9f7d058 ("Documentation: Document each netlink family")
> added recipes for YAML -> RST conversion.
> Then commit 7da8bdbf8f5d ("docs: Makefile: Fix make cleandocs by
> deleting generated .rst files") made sure those converted .rst files
> are cleaned by "make cleandocs".
>
> However, they took care of htmldocs build only.
>
> If one of other targets such as latexdocs or epubdocs is built
> without building htmldocs, missing .rst files can cause additional
> WARNINGs from sphinx-build as follow:
>
>     ./Documentation/userspace-api/netlink/specs.rst:18: WARNING: undefined label: 'specs'
>     ./Documentation/userspace-api/netlink/netlink-raw.rst:64: WARNING: unknown document: '../../networking/netlink_spec/rt_link'
>     ./Documentation/userspace-api/netlink/netlink-raw.rst:64: WARNING: unknown document: '../../networking/netlink_spec/tc'
>     ./Documentation/userspace-api/netlink/index.rst:21: WARNING: undefined label: 'specs'
>
> Add dependency to $(YNL_INDEX) for other targets and allow any targets
> to be built cleanly right after "make cleandocs".
>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Cc: stable@vger.kernel.org  # v6.7
> Cc: Thorsten Blum <thorsten.blum@toblux.com>
> Cc: Breno Leitao <leitao@debian.org>
> Cc: Jakub Kicinski <kuba@kernel.org>
> Cc: David S. Miller <davem@davemloft.net>
> ---
> Hi,
>
> While the first offending commit went through the -net tree, 
> I'd like Jon to pick this up provided there is no objection from
> Jakub or davem.

Applied, thanks.

jon