[LTP] [PATCH v4 4/5] Makefile: Update 'doc' target, add 'doc-clean'

[Ricardo B. Marlière]

On Mon Apr 7, 2025 at 11:53 AM -03, Petr Vorel wrote:
>> Hi Petr,
>
>> On Fri Mar 28, 2025 at 6:57 AM -03, Petr Vorel wrote:
>> > 'doc' target previously run docparse documentation. Point it to doc/
>> > directory so that it build sphinx docs. doc/ dir has metadata/ dir as
>> > dependency, no need to specify it. Call also '.venv' target.
>
>> > NOTE: it's still possible to avoid virtualenv by calling 'make -C doc'
>
>> > Add 'doc-clean': to remove only generated data (not optional .venv).
>
>> > Signed-off-by: Petr Vorel <pvorel@suse.cz>
>> > ---
>> > Changes in v4:
>> > * Use 'setup' instead of '.venv' in the top level doc target
>
>> >  Makefile | 8 +++++++-
>> >  1 file changed, 7 insertions(+), 1 deletion(-)
>
>> > diff --git a/Makefile b/Makefile
>> > index 5066789349..6aa77e1b9b 100644
>> > --- a/Makefile
>> > +++ b/Makefile
>> > @@ -170,7 +170,13 @@ INSTALL_TARGETS		+= $(addprefix $(DESTDIR)/$(bindir)/,$(BINDIR_INSTALL_SCRIPTS))
>> >  $(INSTALL_TARGETS): $(INSTALL_DIR) $(DESTDIR)/$(bindir)
>
>> >  .PHONY: doc
>> > -doc: metadata-all
>> > +doc:
>> > +	$(MAKE) -C $(abs_builddir)/doc setup
>> > +	$(MAKE) -C $(abs_builddir)/doc
>> > +
>> > +.PHONY: doc-clean
>> > +doc-clean:
>> > +	$(MAKE) -C $(abs_builddir)/doc clean
>
>> IMO the top-level clean and distclean targets should be responsible of
>> calling the respective targets in doc/Makefile, what do you think?
>
> Well, we have in the top level other clean targets:
> lib-clean, libs-clean, ac-clean, ac-distclean, ac-maintainer-clean.
> Therefore I thought add at least doc-clean would be good. I ignored
> doc-distclean.
>
> Most of LTP is compiled and therefore handled by
> include/mk/generic_leaf_target.mk. kirk and sparse are special (submodule anyway),
> but even they allows to use generic_leaf_target.mk. I'm not sure if I want to
> rewrite whole doc/Makefile to support generic_leaf_target.mk, I should, but my
> goal was to simplify creating venv. I guess I drop this atm and send v5 and
> without it and get to it later.
>

Right, I tried out something (below) which kind of works but it would require
the setup target becoming the default... The sad part is that even if
the user chooses not to use a virtualenv, linuxdoc does not seem to be
packaged in the major distros (I checked Tumbleweed, Debian and Fedora
only Fedora has it)

diff --git a/Makefile b/Makefile
index 506678934983..69a8016535a9 100644
--- a/Makefile
+++ b/Makefile
@@ -41,7 +41,7 @@ $(1):: | $$(abs_top_builddir)/$$(basename $$(subst -,.,$(1)))
 endif
 endef

-COMMON_TARGETS         += testcases tools metadata
+COMMON_TARGETS         += testcases tools metadata doc

 # Don't want to nuke the original files if we're installing in-build-tree.
 ifneq ($(BUILD_TREE_STATE),$(BUILD_TREE_SRCDIR_INSTALL))
@@ -169,8 +169,8 @@ INSTALL_TARGETS             += $(addprefix $(DESTDIR)/$(bindir)/,$(BINDIR_INSTALL_SCRIPTS))

 $(INSTALL_TARGETS): $(INSTALL_DIR) $(DESTDIR)/$(bindir)

-.PHONY: doc
-doc: metadata-all
+#.PHONY: doc
+#doc: metadata-all

 .PHONY: check
 check: $(CHECK_TARGETS)
diff --git a/doc/Makefile b/doc/Makefile
index 2062d6e93561..7f11e659cab8 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -23,15 +23,17 @@ setup: $(VENV_DIR)
 ${abs_top_builddir}/metadata/ltp.json:
        $(MAKE) -C ${abs_top_builddir}/metadata

-all: ${abs_top_builddir}/metadata/ltp.json
+all: ${abs_top_builddir}/metadata/ltp.json setup
        $(RUN_VENV); sphinx-build -b html . html

 spelling:
        $(RUN_VENV); sphinx-build -b spelling -d build/doctree . build/spelling

-clean:
+clean::
        rm -rf html/ build/ _static/syscalls.rst _static/tests.rst syscalls.tbl \
                ${abs_top_builddir}/metadata/ltp.json

-distclean: clean
+distclean:: clean
        rm -rf $(VENV_DIR)
+
+include $(top_srcdir)/include/mk/generic_leaf_target.mk

Thanks,
		rbm

> Kind regards,
> Petr
>
> The rest of LTP final directories is handled by
> include/mk/generic_leaf_target.mk, but doc/ is somehow special, that's why I
> added these targets.
>
> If you call make clean or distclean
>
>
>> >  .PHONY: check
>> >  check: $(CHECK_TARGETS)