[PATCH] kbuild: add a rule to just create one file for kernel doc

[PATCH] kbuild: add a rule to just create one file for kernel doc

[Sebastian Andrzej Siewior]

If you are chaning the file and you want to verify that it looks good it
is helpfull to just re-run for the single file instead of running the
complete htmldocs target.

With this patch one can run
|	make drivers/mtd/ubi/wl.html
and create the output just for this file.

Cc: Richard Weinberger <richard@nod.at>
Signed-off-by: Sebastian Andrzej Siewior <sebastian@breakpoint.cc>
---
 Makefile               |    2 ++
 scripts/Makefile.build |    6 ++++++
 2 files changed, 8 insertions(+)

diff --git a/Makefile b/Makefile
index 3fdfde2..eccf5cf 100644
--- a/Makefile
+++ b/Makefile
@@ -1338,6 +1338,8 @@ endif
 	$(Q)$(MAKE) $(build)=$(build-dir) $(target-dir)$(notdir $@)
 %.o: %.S prepare scripts FORCE
 	$(Q)$(MAKE) $(build)=$(build-dir) $(target-dir)$(notdir $@)
+%.html: %.c FORCE
+	$(Q)$(MAKE) $(build)=$(build-dir) $(target-dir)$(notdir $@)
 %.symtypes: %.c prepare scripts FORCE
 	$(Q)$(MAKE) $(build)=$(build-dir) $(target-dir)$(notdir $@)
 
diff --git a/scripts/Makefile.build b/scripts/Makefile.build
index ff1720d..75a1823 100644
--- a/scripts/Makefile.build
+++ b/scripts/Makefile.build
@@ -209,6 +209,12 @@ cmd_cc_i_c       = $(CPP) $(c_flags)   -o $@ $<
 $(obj)/%.i: $(src)/%.c FORCE
 	$(call if_changed_dep,cc_i_c)
 
+quiet_cmd_doc_html_c	= HTML $@
+cmd_doc_html_c		= $(srctree)/scripts/kernel-doc -html $< > $@
+
+$(obj)/%.html: $(src)/%.c FORCE
+	$(call if_changed,doc_html_c)
+
 cmd_gensymtypes =                                                           \
     $(CPP) -D__GENKSYMS__ $(c_flags) $< |                                   \
     $(GENKSYMS) $(if $(1), -T $(2)) -a $(ARCH)                              \
-- 
1.7.10

Re: [PATCH] kbuild: add a rule to just create one file for kernel doc

[Richard Weinberger]

[-- Attachment #1: Type: text/plain, Size: 517 bytes --]

Am 26.06.2012 19:40, schrieb Sebastian Andrzej Siewior:
> If you are chaning the file and you want to verify that it looks good it
> is helpfull to just re-run for the single file instead of running the
> complete htmldocs target.
> 
> With this patch one can run
> |	make drivers/mtd/ubi/wl.html
> and create the output just for this file.
> 
> Cc: Richard Weinberger <richard@nod.at>
> Signed-off-by: Sebastian Andrzej Siewior <sebastian@breakpoint.cc>

Acked-by: Richard Weinberger <richard@nod.at>


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 490 bytes --]

Re: [PATCH] kbuild: add a rule to just create one file for kernel doc

[Michal Marek]

On 26.6.2012 19:40, Sebastian Andrzej Siewior wrote:
> If you are chaning the file and you want to verify that it looks good it
> is helpfull to just re-run for the single file instead of running the
> complete htmldocs target.
> 
> With this patch one can run
> |	make drivers/mtd/ubi/wl.html
> and create the output just for this file.

Sounds useful.


> diff --git a/scripts/Makefile.build b/scripts/Makefile.build
> index ff1720d..75a1823 100644
> --- a/scripts/Makefile.build
> +++ b/scripts/Makefile.build
> @@ -209,6 +209,12 @@ cmd_cc_i_c       = $(CPP) $(c_flags)   -o $@ $<
>  $(obj)/%.i: $(src)/%.c FORCE
>  	$(call if_changed_dep,cc_i_c)
>  
> +quiet_cmd_doc_html_c	= HTML $@
> +cmd_doc_html_c		= $(srctree)/scripts/kernel-doc -html $< > $@
> +
> +$(obj)/%.html: $(src)/%.c FORCE
> +	$(call if_changed,doc_html_c)
> +

Could you add this rule to Documentation/DocBook/Makefile instead, so
that scripts/Makefile.build is not needlessly polluted with stuff not
related to compiling and linking?

Thanks!
Michal

[PATCH v2] kbuild: add a rule to just create one file for kernel doc

[Sebastian Andrzej Siewior]

If you are chaning the file and you want to verify that it looks good it
is helpfull to just re-run for the single file instead of running the
complete htmldocs target.

With this patch one can run
|	make drivers/mtd/ubi/wl.html
and create the output just for this file.

Cc: Richard Weinberger <richard@nod.at>
Signed-off-by: Sebastian Andrzej Siewior <sebastian@breakpoint.cc>
---
v1..v2:
	- rules moved to Documentation/DocBook/Makefile instead
	  scripts/Makefile.build
	- added html to clean target

 Documentation/DocBook/Makefile |    8 ++++++++
 Makefile                       |    6 +++++-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index bc3d9f8..423adad 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -204,6 +204,14 @@ silent_gen_xml = :
 	   echo "</programlisting>")  > $@
 
 ###
+# or HTML documentation
+quiet_cmd_doc_html_c	= HTML $@
+cmd_doc_html_c		= $(KERNELDOC) -html $< > $@
+
+%.html: %.c
+	$(call if_changed,doc_html_c)
+
+###
 # Help targets as used by the top-level makefile
 dochelp:
 	@echo  ' Linux kernel internal documentation in different formats:'
diff --git a/Makefile b/Makefile
index bf02707..96ac5d6 100644
--- a/Makefile
+++ b/Makefile
@@ -1079,6 +1079,7 @@ help:
 	@echo  '  dir/file.lst    - Build specified mixed source/assembly target only'
 	@echo  '                    (requires a recent binutils and recent build (System.map))'
 	@echo  '  dir/file.ko     - Build module including final link'
+	@echo  '  dir/file.html   - Build kernel HTML-doc only for this file'
 	@echo  '  modules_prepare - Set up for building external modules'
 	@echo  '  tags/TAGS	  - Generate tags file for editors'
 	@echo  '  cscope	  - Generate cscope index'
@@ -1154,6 +1155,9 @@ $(help-board-dirs): help-%:
 	$(Q)$(MAKE) $(build)=scripts build_docproc
 	$(Q)$(MAKE) $(build)=Documentation/DocBook $@
 
+%.html: %.c FORCE
+	$(Q)$(MAKE) $(build)=Documentation/DocBook $(target-dir)$(notdir $@)
+
 else # KBUILD_EXTMOD
 
 ###
@@ -1240,7 +1244,7 @@ clean: $(clean-dirs)
 	@find $(if $(KBUILD_EXTMOD), $(KBUILD_EXTMOD), .) $(RCS_FIND_IGNORE) \
 		\( -name '*.[oas]' -o -name '*.ko' -o -name '.*.cmd' \
 		-o -name '.*.d' -o -name '.*.tmp' -o -name '*.mod.c' \
-		-o -name '*.symtypes' -o -name 'modules.order' \
+		-o -name '*.symtypes' -o -name 'modules.order' -o -name *.html \
 		-o -name modules.builtin -o -name '.tmp_*.o.*' \
 		-o -name '*.gcno' \) -type f -print | xargs rm -f
 
-- 
1.7.10.4