[LTP] [PATCH v4 0/5] Update doc related Makefile

[LTP] [PATCH v4 0/5] Update doc related Makefile

[Petr Vorel]

Changes from v3 (all by Andrea):

* Add setup (alias to .venv)
* Move sphinx to requirements.txt (therefore remove handling in Makefile)
* Add support also for fish (csh/tcsh ignored, supporting: fish, bash/zsh)
* Use 'setup' instead of '.venv' in the top level doc target

NOTE: 'distclean' of doc/ directory is not in the top level directory
(IMHO not needed).

Are we there yet?

Kind regards,
Petr

Link to v3:
https://patchwork.ozlabs.org/project/ltp/list/?series=449828&state=*
https://lore.kernel.org/ltp/20250324234016.367228-1-pvorel@suse.cz/T/#t

Link to v2:
https://patchwork.ozlabs.org/project/ltp/list/?series=443894&state=*
https://lore.kernel.org/ltp/20250211233552.1990618-1-pvorel@suse.cz/#r

Link to v1:
https://patchwork.ozlabs.org/project/ltp/patch/20250206143421.1571918-4-pvorel@suse.cz/
https://lore.kernel.org/ltp/20250206143421.1571918-4-pvorel@suse.cz/

Petr Vorel (5):
  doc/Makefile: Remove also metadata/ltp.json
  doc: Add sphinx to requirements.txt
  doc/Makefile: Allow to create and use .venv
  Makefile: Update 'doc' target, add 'doc-clean'
  doc: Note 'make doc' in the building doc

 Makefile                         |  8 +++++++-
 doc/Makefile                     | 25 ++++++++++++++++++++++---
 doc/developers/documentation.rst |  4 ++--
 doc/requirements.txt             |  1 +
 4 files changed, 32 insertions(+), 6 deletions(-)

-- 
2.49.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

[LTP] [PATCH v4 1/5] doc/Makefile: Remove also metadata/ltp.json

[Petr Vorel]

Because there is no detection whether tests changed it's better to
remove JSON file on metadata cleanup.

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
The same as in previous version.

 doc/Makefile | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/Makefile b/doc/Makefile
index a07df04d5c..3c5682ad00 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -15,4 +15,5 @@ spelling:
 	sphinx-build -b spelling -d build/doctree . build/spelling
 
 clean:
-	rm -rf html/ build/ _static/syscalls.rst _static/tests.rst syscalls.tbl
+	rm -rf html/ build/ _static/syscalls.rst _static/tests.rst syscalls.tbl \
+		${abs_top_builddir}/metadata/ltp.json
-- 
2.49.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

[LTP] [PATCH v4 2/5] doc: Add sphinx to requirements.txt

[Petr Vorel]

Although that slightly prolongs creating virtualenv, it's probably
better to handle it as the other requirements.

Suggested-by: Andrea Cervesato <andrea.cervesato@suse.com>
Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
New in v4.

 doc/developers/documentation.rst | 2 --
 doc/requirements.txt             | 1 +
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/doc/developers/documentation.rst b/doc/developers/documentation.rst
index 27c847e125..a303253693 100644
--- a/doc/developers/documentation.rst
+++ b/doc/developers/documentation.rst
@@ -23,8 +23,6 @@ Before building, make sure you have python3 ``virtualenv`` module installed.
     # prepare virtual environment
     python3 -m virtualenv .venv
     . .venv/bin/activate
-
-    pip install sphinx # usually packaged in distros
     pip install -r requirements.txt
 
     # build documentation
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 742fb8b4bb..1f4cefb2c6 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,3 +1,4 @@
+sphinx
 sphinx-rtd-theme==2.0.0
 linuxdoc==20231020
 sphinxcontrib-spelling==7.7.0
-- 
2.49.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH v4 2/5] doc: Add sphinx to requirements.txt

[Andrea Cervesato via ltp]

Hi Petr,

On 3/28/25 10:57, Petr Vorel wrote:
> Although that slightly prolongs creating virtualenv, it's probably
> better to handle it as the other requirements.
>
> Suggested-by: Andrea Cervesato <andrea.cervesato@suse.com>
> Signed-off-by: Petr Vorel <pvorel@suse.cz>
> ---
> New in v4.
>
>   doc/developers/documentation.rst | 2 --
>   doc/requirements.txt             | 1 +
>   2 files changed, 1 insertion(+), 2 deletions(-)
>
> diff --git a/doc/developers/documentation.rst b/doc/developers/documentation.rst
> index 27c847e125..a303253693 100644
> --- a/doc/developers/documentation.rst
> +++ b/doc/developers/documentation.rst
> @@ -23,8 +23,6 @@ Before building, make sure you have python3 ``virtualenv`` module installed.
>       # prepare virtual environment
>       python3 -m virtualenv .venv
>       . .venv/bin/activate
> -
> -    pip install sphinx # usually packaged in distros
>       pip install -r requirements.txt
>   
>       # build documentation
> diff --git a/doc/requirements.txt b/doc/requirements.txt
> index 742fb8b4bb..1f4cefb2c6 100644
> --- a/doc/requirements.txt
> +++ b/doc/requirements.txt
> @@ -1,3 +1,4 @@
> +sphinx
In requirements.txt we usually put the right version of the package that 
we want to use. We can use the latest, what do you think?
>   sphinx-rtd-theme==2.0.0
>   linuxdoc==20231020
>   sphinxcontrib-spelling==7.7.0
Andrea

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH v4 2/5] doc: Add sphinx to requirements.txt

[Petr Vorel]

> Hi Petr,

> On 3/28/25 10:57, Petr Vorel wrote:
> > Although that slightly prolongs creating virtualenv, it's probably
> > better to handle it as the other requirements.

> > Suggested-by: Andrea Cervesato <andrea.cervesato@suse.com>
> > Signed-off-by: Petr Vorel <pvorel@suse.cz>
> > ---
> > New in v4.

> >   doc/developers/documentation.rst | 2 --
> >   doc/requirements.txt             | 1 +
> >   2 files changed, 1 insertion(+), 2 deletions(-)

> > diff --git a/doc/developers/documentation.rst b/doc/developers/documentation.rst
> > index 27c847e125..a303253693 100644
> > --- a/doc/developers/documentation.rst
> > +++ b/doc/developers/documentation.rst
> > @@ -23,8 +23,6 @@ Before building, make sure you have python3 ``virtualenv`` module installed.
> >       # prepare virtual environment
> >       python3 -m virtualenv .venv
> >       . .venv/bin/activate
> > -
> > -    pip install sphinx # usually packaged in distros
> >       pip install -r requirements.txt
> >       # build documentation
> > diff --git a/doc/requirements.txt b/doc/requirements.txt
> > index 742fb8b4bb..1f4cefb2c6 100644
> > --- a/doc/requirements.txt
> > +++ b/doc/requirements.txt
> > @@ -1,3 +1,4 @@
> > +sphinx
> In requirements.txt we usually put the right version of the package that we
> want to use. We can use the latest, what do you think?

I hesitated a bit if fixed versions are the best as sooner or later will have to
be manually updated when it breaks, but sure - we use it anyway for other modules

-sphinx
-sphinx-rtd-theme==2.0.0
+sphinx==8.2.3
+sphinx-rtd-theme==3.0.2

In that case I would remove python3-sphinx from apt install command in
.github/workflows/ci-sphinx-doc.yml to match the command => I'll send v5
of this change only.

Kind regards,
Petr

> >   sphinx-rtd-theme==2.0.0
> >   linuxdoc==20231020
> >   sphinxcontrib-spelling==7.7.0
> Andrea

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH v4 2/5] doc: Add sphinx to requirements.txt

[Petr Vorel]

> > Hi Petr,

> > On 3/28/25 10:57, Petr Vorel wrote:
> > > Although that slightly prolongs creating virtualenv, it's probably
> > > better to handle it as the other requirements.

> > > Suggested-by: Andrea Cervesato <andrea.cervesato@suse.com>
> > > Signed-off-by: Petr Vorel <pvorel@suse.cz>
> > > ---
> > > New in v4.

> > >   doc/developers/documentation.rst | 2 --
> > >   doc/requirements.txt             | 1 +
> > >   2 files changed, 1 insertion(+), 2 deletions(-)

> > > diff --git a/doc/developers/documentation.rst b/doc/developers/documentation.rst
> > > index 27c847e125..a303253693 100644
> > > --- a/doc/developers/documentation.rst
> > > +++ b/doc/developers/documentation.rst
> > > @@ -23,8 +23,6 @@ Before building, make sure you have python3 ``virtualenv`` module installed.
> > >       # prepare virtual environment
> > >       python3 -m virtualenv .venv
> > >       . .venv/bin/activate
> > > -
> > > -    pip install sphinx # usually packaged in distros
> > >       pip install -r requirements.txt
> > >       # build documentation
> > > diff --git a/doc/requirements.txt b/doc/requirements.txt
> > > index 742fb8b4bb..1f4cefb2c6 100644
> > > --- a/doc/requirements.txt
> > > +++ b/doc/requirements.txt
> > > @@ -1,3 +1,4 @@
> > > +sphinx
> > In requirements.txt we usually put the right version of the package that we
> > want to use. We can use the latest, what do you think?

> I hesitated a bit if fixed versions are the best as sooner or later will have to
> be manually updated when it breaks, but sure - we use it anyway for other modules

> -sphinx
> -sphinx-rtd-theme==2.0.0
> +sphinx==8.2.3
> +sphinx-rtd-theme==3.0.2

> In that case I would remove python3-sphinx from apt install command in
> .github/workflows/ci-sphinx-doc.yml to match the command => I'll send v5
> of this change only.

Wait, one thing: we use doc/requirements.txt in .readthedocs.yml. Is it really a
good idea to add there sphinx, when it uses containers? I can test it in a
separate branch, but we discussed some time ago that we should avoid adding
sphinx for readthedocs.

Wouldn't be in the end better to keep 'pip install sphinx' in Makefile instead
(the previous proposal).

Kind regards,
Petr

> Kind regards,
> Petr

> > >   sphinx-rtd-theme==2.0.0
> > >   linuxdoc==20231020
> > >   sphinxcontrib-spelling==7.7.0
> > Andrea

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH v4 2/5] doc: Add sphinx to requirements.txt

[Andrea Cervesato via ltp]

On 3/31/25 18:37, Petr Vorel wrote:
> Wait, one thing: we use doc/requirements.txt in .readthedocs.yml. Is it really a
> good idea to add there sphinx, when it uses containers? I can test it in a
> separate branch, but we discussed some time ago that we should avoid adding
> sphinx for readthedocs.
>
> Wouldn't be in the end better to keep 'pip install sphinx' in Makefile instead
> (the previous proposal).
>
> Kind regards,
> Petr

I forgot about it. Thanks for remembering. At the moment readthedocs 
installs sphinx via pip, so if we add just sphinx ro requirements.txt 
without version, pip should reinstall the same version which is already 
available before building the website.

We should give a try and eventually get back to the old way.

Andrea


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH v4 2/5] doc: Add sphinx to requirements.txt

[Petr Vorel]

> On 3/31/25 18:37, Petr Vorel wrote:
> > Wait, one thing: we use doc/requirements.txt in .readthedocs.yml. Is it really a
> > good idea to add there sphinx, when it uses containers? I can test it in a
> > separate branch, but we discussed some time ago that we should avoid adding
> > sphinx for readthedocs.

> > Wouldn't be in the end better to keep 'pip install sphinx' in Makefile instead
> > (the previous proposal).

> > Kind regards,
> > Petr

> I forgot about it. Thanks for remembering. At the moment readthedocs
> installs sphinx via pip, so if we add just sphinx ro requirements.txt
> without version, pip should reinstall the same version which is already
> available before building the website.

> We should give a try and eventually get back to the old way.

To be honest I would prefer to avoid experimenting with readthedoc as much as
possible. How about just forcing 'pip install sphinx' only in Makefile?
It can be the simplest version - without checking if it's installed.

Because I don't see any benefit to add sphinx to readthedocs where it's not
needed - in the best case it will takes time to reinstall, in worst it just take
time to experiment to find it breaks things. We are going to diverge from
readthedocs anyway, unless we manually sync with the sphinx version it uses.
You asked for newest version (which is 8.2.3, if I don't count broken 8.3),
but in readthedocs we use old ubuntu-22.04, which uses sphinx 4.3.2 [1].

We could update to noble (24.04LTS) (if supported by readthedocs) to get newer
7.2.6 (as I can test it as a separate effort.

[1] https://packages.ubuntu.com/jammy/python3-sphinx
[2] https://packages.ubuntu.com/noble/python3-sphinx

I guess controlling the version is important, therefore I would prefer b) or c).

a) simple version in Makefile, without version:

$(VENV_DIR):
	$(PYTHON) -m virtualenv $(VENV_DIR)
	$(VENV_CMD) && pip install sphinx && pip install -r requirements.txt

b) simple version with specifying sphinx version:

SPHINX_VERSION := 8.2.3 # or 7.2.6 or 4.3.2?
...
$(VENV_DIR):
	$(PYTHON) -m virtualenv $(VENV_DIR)
	$(VENV_CMD) && pip install sphinx==$(SPHINX_VERSION) && pip install -r requirements.txt

c) more complicated version (you did not like) which install sphinx only when
needed:

SPHINX_VERSION := 8.2.3
INSTALL_SPHINX := $(shell $(PYTHON) -c "import sphinx" 2>/dev/null && echo ":" || echo "pip install sphinx==$(SPHINX_VERSION)")
...
$(VENV_DIR):
	$(PYTHON) -m virtualenv $(VENV_DIR)
	$(VENV_CMD) && pip install -r requirements.txt && $(INSTALL_SPHINX)

Kind regards,
Petr

> Andrea


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH v4 2/5] doc: Add sphinx to requirements.txt

[Andrea Cervesato via ltp]

On 3/31/25 19:53, Petr Vorel wrote:
>> On 3/31/25 18:37, Petr Vorel wrote:
>>> Wait, one thing: we use doc/requirements.txt in .readthedocs.yml. Is it really a
>>> good idea to add there sphinx, when it uses containers? I can test it in a
>>> separate branch, but we discussed some time ago that we should avoid adding
>>> sphinx for readthedocs.
>>> Wouldn't be in the end better to keep 'pip install sphinx' in Makefile instead
>>> (the previous proposal).
>>> Kind regards,
>>> Petr
>> I forgot about it. Thanks for remembering. At the moment readthedocs
>> installs sphinx via pip, so if we add just sphinx ro requirements.txt
>> without version, pip should reinstall the same version which is already
>> available before building the website.
>> We should give a try and eventually get back to the old way.
> To be honest I would prefer to avoid experimenting with readthedoc as much as
> possible. How about just forcing 'pip install sphinx' only in Makefile?
> It can be the simplest version - without checking if it's installed.
The thing is that readthedoc is already doing "pip install sphinx" 
before building the website, so any other "pip install sphinx" or "pip 
install requirements.txt" (with sphinx in it) won't create issues. pip 
will check the cache, finding sphinx already installed and it will skip 
its installation.

The only thing we should avoid is the usage of sphinx version. So we 
just keep "sphinx" as a generic package inside requirements.txt and pip 
will take care about the version.

> Because I don't see any benefit to add sphinx to readthedocs where it's not
> needed - in the best case it will takes time to reinstall, in worst it just take
> time to experiment to find it breaks things. We are going to diverge from
> readthedocs anyway, unless we manually sync with the sphinx version it uses.
> You asked for newest version (which is 8.2.3, if I don't count broken 8.3),
> but in readthedocs we use old ubuntu-22.04, which uses sphinx 4.3.2 [1].
>
> We could update to noble (24.04LTS) (if supported by readthedocs) to get newer
> 7.2.6 (as I can test it as a separate effort.
>
> [1] https://packages.ubuntu.com/jammy/python3-sphinx
> [2] https://packages.ubuntu.com/noble/python3-sphinx
>
> I guess controlling the version is important, therefore I would prefer b) or c).
>
> a) simple version in Makefile, without version:
>
> $(VENV_DIR):
> 	$(PYTHON) -m virtualenv $(VENV_DIR)
> 	$(VENV_CMD) && pip install sphinx && pip install -r requirements.txt
>
> b) simple version with specifying sphinx version:
>
> SPHINX_VERSION := 8.2.3 # or 7.2.6 or 4.3.2?
> ...
> $(VENV_DIR):
> 	$(PYTHON) -m virtualenv $(VENV_DIR)
> 	$(VENV_CMD) && pip install sphinx==$(SPHINX_VERSION) && pip install -r requirements.txt
>
> c) more complicated version (you did not like) which install sphinx only when
> needed:
>
> SPHINX_VERSION := 8.2.3
> INSTALL_SPHINX := $(shell $(PYTHON) -c "import sphinx" 2>/dev/null && echo ":" || echo "pip install sphinx==$(SPHINX_VERSION)")
> ...
> $(VENV_DIR):
> 	$(PYTHON) -m virtualenv $(VENV_DIR)
> 	$(VENV_CMD) && pip install -r requirements.txt && $(INSTALL_SPHINX)
>
> Kind regards,
> Petr
>
>> Andrea
Andrea

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH v4 2/5] doc: Add sphinx to requirements.txt

[Petr Vorel]

> On 3/31/25 19:53, Petr Vorel wrote:
> > > On 3/31/25 18:37, Petr Vorel wrote:
> > > > Wait, one thing: we use doc/requirements.txt in .readthedocs.yml. Is it really a
> > > > good idea to add there sphinx, when it uses containers? I can test it in a
> > > > separate branch, but we discussed some time ago that we should avoid adding
> > > > sphinx for readthedocs.
> > > > Wouldn't be in the end better to keep 'pip install sphinx' in Makefile instead
> > > > (the previous proposal).
> > > > Kind regards,
> > > > Petr
> > > I forgot about it. Thanks for remembering. At the moment readthedocs
> > > installs sphinx via pip, so if we add just sphinx ro requirements.txt
> > > without version, pip should reinstall the same version which is already
> > > available before building the website.
> > > We should give a try and eventually get back to the old way.
> > To be honest I would prefer to avoid experimenting with readthedoc as much as
> > possible. How about just forcing 'pip install sphinx' only in Makefile?
> > It can be the simplest version - without checking if it's installed.
> The thing is that readthedoc is already doing "pip install sphinx" before
> building the website, so any other "pip install sphinx" or "pip install
> requirements.txt" (with sphinx in it) won't create issues. pip will check
> the cache, finding sphinx already installed and it will skip its
> installation.

> The only thing we should avoid is the usage of sphinx version. So we just
> keep "sphinx" as a generic package inside requirements.txt and pip will take
> care about the version.

Of course we have to *not* version also sphinx-rtd-theme, because it's release
is tight to sphinx version. That was obvious (2.0.0 requires sphinx < 8), but I
tried it in our readthedocs.org to verify it really fails.

IMHO it'd be better to keep sphinx and sphinx-rtd-theme to these which are used
in readthedocs.org. Because that way we still use the same version (we control
the version used in readthedocs.org via os version used in .readthedocs.yml.

Kind regards,
Petr

> > Because I don't see any benefit to add sphinx to readthedocs where it's not
> > needed - in the best case it will takes time to reinstall, in worst it just take
> > time to experiment to find it breaks things. We are going to diverge from
> > readthedocs anyway, unless we manually sync with the sphinx version it uses.
> > You asked for newest version (which is 8.2.3, if I don't count broken 8.3),
> > but in readthedocs we use old ubuntu-22.04, which uses sphinx 4.3.2 [1].

> > We could update to noble (24.04LTS) (if supported by readthedocs) to get newer
> > 7.2.6 (as I can test it as a separate effort.

> > [1] https://packages.ubuntu.com/jammy/python3-sphinx
> > [2] https://packages.ubuntu.com/noble/python3-sphinx

> > I guess controlling the version is important, therefore I would prefer b) or c).

> > a) simple version in Makefile, without version:

> > $(VENV_DIR):
> > 	$(PYTHON) -m virtualenv $(VENV_DIR)
> > 	$(VENV_CMD) && pip install sphinx && pip install -r requirements.txt

> > b) simple version with specifying sphinx version:

> > SPHINX_VERSION := 8.2.3 # or 7.2.6 or 4.3.2?
> > ...
> > $(VENV_DIR):
> > 	$(PYTHON) -m virtualenv $(VENV_DIR)
> > 	$(VENV_CMD) && pip install sphinx==$(SPHINX_VERSION) && pip install -r requirements.txt

> > c) more complicated version (you did not like) which install sphinx only when
> > needed:

> > SPHINX_VERSION := 8.2.3
> > INSTALL_SPHINX := $(shell $(PYTHON) -c "import sphinx" 2>/dev/null && echo ":" || echo "pip install sphinx==$(SPHINX_VERSION)")
> > ...
> > $(VENV_DIR):
> > 	$(PYTHON) -m virtualenv $(VENV_DIR)
> > 	$(VENV_CMD) && pip install -r requirements.txt && $(INSTALL_SPHINX)

> > Kind regards,
> > Petr

> > > Andrea
> Andrea

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH v4 2/5] doc: Add sphinx to requirements.txt

[Petr Vorel]

> > On 3/31/25 19:53, Petr Vorel wrote:
> > > > On 3/31/25 18:37, Petr Vorel wrote:
> > > > > Wait, one thing: we use doc/requirements.txt in .readthedocs.yml. Is it really a
> > > > > good idea to add there sphinx, when it uses containers? I can test it in a
> > > > > separate branch, but we discussed some time ago that we should avoid adding
> > > > > sphinx for readthedocs.
> > > > > Wouldn't be in the end better to keep 'pip install sphinx' in Makefile instead
> > > > > (the previous proposal).
> > > > > Kind regards,
> > > > > Petr
> > > > I forgot about it. Thanks for remembering. At the moment readthedocs
> > > > installs sphinx via pip, so if we add just sphinx ro requirements.txt
> > > > without version, pip should reinstall the same version which is already
> > > > available before building the website.
> > > > We should give a try and eventually get back to the old way.
> > > To be honest I would prefer to avoid experimenting with readthedoc as much as
> > > possible. How about just forcing 'pip install sphinx' only in Makefile?
> > > It can be the simplest version - without checking if it's installed.
> > The thing is that readthedoc is already doing "pip install sphinx" before
> > building the website, so any other "pip install sphinx" or "pip install
> > requirements.txt" (with sphinx in it) won't create issues. pip will check
> > the cache, finding sphinx already installed and it will skip its
> > installation.

> > The only thing we should avoid is the usage of sphinx version. So we just
> > keep "sphinx" as a generic package inside requirements.txt and pip will take
> > care about the version.

> Of course we have to *not* version also sphinx-rtd-theme, because it's release
> is tight to sphinx version. That was obvious (2.0.0 requires sphinx < 8), but I
> tried it in our readthedocs.org to verify it really fails.

> IMHO it'd be better to keep sphinx and sphinx-rtd-theme to these which are used
> in readthedocs.org. Because that way we still use the same version (we control
> the version used in readthedocs.org via os version used in .readthedocs.yml.

I missed the main point for using the same sphinx version for development and
for the real docs in readthedocs.org: we get changes tested (both in CI job and
hopefully with development) if we use the same version. Because different
version can have incompatibilities which we discover once it gets broken on
readthedocs.org :(.

Kind regards,
Petr

> Kind regards,
> Petr

> > > Because I don't see any benefit to add sphinx to readthedocs where it's not
> > > needed - in the best case it will takes time to reinstall, in worst it just take
> > > time to experiment to find it breaks things. We are going to diverge from
> > > readthedocs anyway, unless we manually sync with the sphinx version it uses.
> > > You asked for newest version (which is 8.2.3, if I don't count broken 8.3),
> > > but in readthedocs we use old ubuntu-22.04, which uses sphinx 4.3.2 [1].

> > > We could update to noble (24.04LTS) (if supported by readthedocs) to get newer
> > > 7.2.6 (as I can test it as a separate effort.

> > > [1] https://packages.ubuntu.com/jammy/python3-sphinx
> > > [2] https://packages.ubuntu.com/noble/python3-sphinx

> > > I guess controlling the version is important, therefore I would prefer b) or c).

> > > a) simple version in Makefile, without version:

> > > $(VENV_DIR):
> > > 	$(PYTHON) -m virtualenv $(VENV_DIR)
> > > 	$(VENV_CMD) && pip install sphinx && pip install -r requirements.txt

> > > b) simple version with specifying sphinx version:

> > > SPHINX_VERSION := 8.2.3 # or 7.2.6 or 4.3.2?
> > > ...
> > > $(VENV_DIR):
> > > 	$(PYTHON) -m virtualenv $(VENV_DIR)
> > > 	$(VENV_CMD) && pip install sphinx==$(SPHINX_VERSION) && pip install -r requirements.txt

> > > c) more complicated version (you did not like) which install sphinx only when
> > > needed:

> > > SPHINX_VERSION := 8.2.3
> > > INSTALL_SPHINX := $(shell $(PYTHON) -c "import sphinx" 2>/dev/null && echo ":" || echo "pip install sphinx==$(SPHINX_VERSION)")
> > > ...
> > > $(VENV_DIR):
> > > 	$(PYTHON) -m virtualenv $(VENV_DIR)
> > > 	$(VENV_CMD) && pip install -r requirements.txt && $(INSTALL_SPHINX)

> > > Kind regards,
> > > Petr

> > > > Andrea
> > Andrea

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

[LTP] [PATCH v4 3/5] doc/Makefile: Allow to create and use .venv

[Petr Vorel]

Add 'setup' target (alias to '.venv') to create virtualenv directory.
This is an optional target (not run by default).
If .venv exists, it's used in other targets, activation supports only
fish and bash/zsh (known shells used by LTP developers, csh/tcsh is
ignored atm).

This helps to use virtualenv for development, but avoid using it by
default (readthedoc uses container with virtualenv, creating it would be
waste of time).

Add 'distclean' target which removes also .venv/ directory.

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
Changes in v4:
* Add setup (alias to .venv)
* Move sphinx to requirements.txt (therefore remove handling in Makefile)
* Add support also for fish (csh/tcsh ignored, supporting: fish, bash/zsh)

 doc/Makefile | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/doc/Makefile b/doc/Makefile
index 3c5682ad00..2062d6e935 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -5,15 +5,33 @@ top_srcdir		?= ..
 
 include $(top_srcdir)/include/mk/env_pre.mk
 
+PYTHON := python3
+VENV_DIR := .venv
+
+# only fish and bash/zsh supported
+VENV_CMD := if [ "x${FISH_VERSION}" != "x" ]; then . $(VENV_DIR)/bin/activate.fish; else . $(VENV_DIR)/bin/activate; fi
+
+RUN_VENV := if [ -d $(VENV_DIR) ]; then $(VENV_CMD); fi
+
+$(VENV_DIR):
+	$(PYTHON) -m virtualenv $(VENV_DIR)
+	$(VENV_CMD) && pip install -r requirements.txt
+
+.PHONY: setup
+setup: $(VENV_DIR)
+
 ${abs_top_builddir}/metadata/ltp.json:
 	$(MAKE) -C ${abs_top_builddir}/metadata
 
 all: ${abs_top_builddir}/metadata/ltp.json
-	sphinx-build -b html . html
+	$(RUN_VENV); sphinx-build -b html . html
 
 spelling:
-	sphinx-build -b spelling -d build/doctree . build/spelling
+	$(RUN_VENV); sphinx-build -b spelling -d build/doctree . build/spelling
 
 clean:
 	rm -rf html/ build/ _static/syscalls.rst _static/tests.rst syscalls.tbl \
 		${abs_top_builddir}/metadata/ltp.json
+
+distclean: clean
+	rm -rf $(VENV_DIR)
-- 
2.49.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH v4 3/5] doc/Makefile: Allow to create and use .venv

[Andrea Cervesato via ltp]

Hi,

Reviewed-by: Andrea Cervesato <andrea.cervesato@suse.com>

On 3/28/25 10:57, Petr Vorel wrote:
> Add 'setup' target (alias to '.venv') to create virtualenv directory.
> This is an optional target (not run by default).
> If .venv exists, it's used in other targets, activation supports only
> fish and bash/zsh (known shells used by LTP developers, csh/tcsh is
> ignored atm).
>
> This helps to use virtualenv for development, but avoid using it by
> default (readthedoc uses container with virtualenv, creating it would be
> waste of time).
>
> Add 'distclean' target which removes also .venv/ directory.
>
> Signed-off-by: Petr Vorel <pvorel@suse.cz>
> ---
> Changes in v4:
> * Add setup (alias to .venv)
> * Move sphinx to requirements.txt (therefore remove handling in Makefile)
> * Add support also for fish (csh/tcsh ignored, supporting: fish, bash/zsh)
>
>   doc/Makefile | 22 ++++++++++++++++++++--
>   1 file changed, 20 insertions(+), 2 deletions(-)
>
> diff --git a/doc/Makefile b/doc/Makefile
> index 3c5682ad00..2062d6e935 100644
> --- a/doc/Makefile
> +++ b/doc/Makefile
> @@ -5,15 +5,33 @@ top_srcdir		?= ..
>   
>   include $(top_srcdir)/include/mk/env_pre.mk
>   
> +PYTHON := python3
> +VENV_DIR := .venv
> +
> +# only fish and bash/zsh supported
> +VENV_CMD := if [ "x${FISH_VERSION}" != "x" ]; then . $(VENV_DIR)/bin/activate.fish; else . $(VENV_DIR)/bin/activate; fi
> +
> +RUN_VENV := if [ -d $(VENV_DIR) ]; then $(VENV_CMD); fi
> +
> +$(VENV_DIR):
> +	$(PYTHON) -m virtualenv $(VENV_DIR)
> +	$(VENV_CMD) && pip install -r requirements.txt
> +
> +.PHONY: setup
> +setup: $(VENV_DIR)
> +
>   ${abs_top_builddir}/metadata/ltp.json:
>   	$(MAKE) -C ${abs_top_builddir}/metadata
>   
>   all: ${abs_top_builddir}/metadata/ltp.json
> -	sphinx-build -b html . html
> +	$(RUN_VENV); sphinx-build -b html . html
>   
>   spelling:
> -	sphinx-build -b spelling -d build/doctree . build/spelling
> +	$(RUN_VENV); sphinx-build -b spelling -d build/doctree . build/spelling
>   
>   clean:
>   	rm -rf html/ build/ _static/syscalls.rst _static/tests.rst syscalls.tbl \
>   		${abs_top_builddir}/metadata/ltp.json
> +
> +distclean: clean
> +	rm -rf $(VENV_DIR)

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

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

[Petr Vorel]

'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
 
 .PHONY: check
 check: $(CHECK_TARGETS)
-- 
2.49.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

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

[Ricardo B. Marli��re via ltp]

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?

>  
>  .PHONY: check
>  check: $(CHECK_TARGETS)


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

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

[Petr Vorel]

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

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)


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

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

[Ricardo B. Marli��re via ltp]

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)


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

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

[Petr Vorel]

Hi Ricardo,

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

I'm surprised that any distro package linuxdoc. And IMHO all linux distros
require pip install to run inside virtualenv.

> 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

I was testing doc part of COMMON_TARGETS as well (that requires that
generic_leaf_target.mk to be included). But that means that doc will be always
built, which means that user either has linuxdoc and others installed as a
package or via 'make -C doc setup'.

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

'doc: metadata-all' is a part I suggested to be deleted (useless now).
But IMHO it should be replaced by other phony target - my plan was to use
generic_leaf_target.mk (reuse existing LTP build system instead writing from
scratch), but don't have doc/ part of build from top level Makefile (avoid
dealing with virtualenv). Therefore I guess at least doc target in this patchset
is more or less correct. Maybe having doc as a part of CLEAN_TARGETS
variable will work.

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

Using virtualenv by default was something which Andrea did not want (equivalent
of this was in my v1). And I agree we don't want packagers to deal with
virtualenv (FYI atm there are at least SUSE, Buildroot and Yocto packages; Red
hat plans to use it as well).

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

> -clean:
> +clean::
+1, I did not have enough time to figure out '::'.

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


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

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

[Ricardo B. Marli��re via ltp]

On Wed Apr 9, 2025 at 5:12 AM -03, Petr Vorel wrote:
> Hi Ricardo,
>
>> >> > -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)
>
> I'm surprised that any distro package linuxdoc. And IMHO all linux distros
> require pip install to run inside virtualenv.
>

I was surprise it isn't :(

>> 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
>
> I was testing doc part of COMMON_TARGETS as well (that requires that
> generic_leaf_target.mk to be included). But that means that doc will be always
> built, which means that user either has linuxdoc and others installed as a
> package or via 'make -C doc setup'.
>

+1

>>  # 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
>
> 'doc: metadata-all' is a part I suggested to be deleted (useless now).
> But IMHO it should be replaced by other phony target - my plan was to use
> generic_leaf_target.mk (reuse existing LTP build system instead writing from
> scratch), but don't have doc/ part of build from top level Makefile (avoid
> dealing with virtualenv). Therefore I guess at least doc target in this patchset
> is more or less correct. Maybe having doc as a part of CLEAN_TARGETS
> variable will work.

Adding it to CLEAN_TARGETS will work, as it will create the `doc-clean`
target.

>
>>  .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
>
> Using virtualenv by default was something which Andrea did not want (equivalent
> of this was in my v1). And I agree we don't want packagers to deal with
> virtualenv (FYI atm there are at least SUSE, Buildroot and Yocto packages; Red
> hat plans to use it as well).
>

Hm, but if we have a top-level target "doc" which setup the venv by
default, it will be even more confusing... Maybe having both doc and
doc-setup would make sense?

With this, we can opt-in the venv by doing `make doc-setup` first. We
can clean it with `make doc-clean` or the top-level `make clean` and
`make distclean`

>>  spelling:
>>         $(RUN_VENV); sphinx-build -b spelling -d build/doctree . build/spelling
>
>> -clean:
>> +clean::
> +1, I did not have enough time to figure out '::'.
>
>>         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)


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

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

[Petr Vorel]

Hi Ricardo,

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

> > I'm surprised that any distro package linuxdoc. And IMHO all linux distros
> > require pip install to run inside virtualenv.


> I was surprise it isn't :(

IMHO kernel developers do very little packaging. And the rest does not care
about (it's not mandatory for building a distro kernel, it's only for publishing
on https://docs.kernel.org/). I would guess quite a lot of kernel maintainers
use Fedora (and Debian) maybe the reason why it's there.

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

> > I was testing doc part of COMMON_TARGETS as well (that requires that
> > generic_leaf_target.mk to be included). But that means that doc will be always
> > built, which means that user either has linuxdoc and others installed as a
> > package or via 'make -C doc setup'.


> +1

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

> > 'doc: metadata-all' is a part I suggested to be deleted (useless now).
> > But IMHO it should be replaced by other phony target - my plan was to use
> > generic_leaf_target.mk (reuse existing LTP build system instead writing from
> > scratch), but don't have doc/ part of build from top level Makefile (avoid
> > dealing with virtualenv). Therefore I guess at least doc target in this patchset
> > is more or less correct. Maybe having doc as a part of CLEAN_TARGETS
> > variable will work.

> Adding it to CLEAN_TARGETS will work, as it will create the `doc-clean`
> target.

+1. I hope it creates also doc-distclean (to remove doc/.venv).


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

> > Using virtualenv by default was something which Andrea did not want (equivalent
> > of this was in my v1). And I agree we don't want packagers to deal with
> > virtualenv (FYI atm there are at least SUSE, Buildroot and Yocto packages; Red
> > hat plans to use it as well).


> Hm, but if we have a top-level target "doc" which setup the venv by
> default, it will be even more confusing... Maybe having both doc and
> doc-setup would make sense?

> With this, we can opt-in the venv by doing `make doc-setup` first. We
> can clean it with `make doc-clean` or the top-level `make clean` and
> `make distclean`

It is confusing, but it would be documented.

I wanted top level doc to be as easiest as possible. And generally have top
level targets as simple as possible (shortcuts - go to LTP git directory and
type short make target to have things done):

make -C doc # without venv

make doc # for venv
(shorter than make doc-setup; make doc)

But if you consider it too confusing, it's not that long the targets you
suggest. It'd be nice to have opinion from others.

Kind regards,
Petr

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

[LTP] [PATCH v4 5/5] doc: Note 'make doc' in the building doc

[Petr Vorel]

Update doc by changes in previous commits.

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
The same as in previous version.

 doc/developers/documentation.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/doc/developers/documentation.rst b/doc/developers/documentation.rst
index a303253693..14dc97bcd8 100644
--- a/doc/developers/documentation.rst
+++ b/doc/developers/documentation.rst
@@ -28,6 +28,8 @@ Before building, make sure you have python3 ``virtualenv`` module installed.
     # build documentation
     make
 
+Instead of the above it's possible call ``make doc`` in the top level directory.
+
 Once the procedure has been completed, documentation will be visible at
 ``doc/html/index.html``.
 
-- 
2.49.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH v4 0/5] Update doc related Makefile

[Andrea Cervesato via ltp]

Hi Petr,

Reviewed-by: Andrea Cervesato <andrea.cervesato@suse.com>

On 3/28/25 10:57, Petr Vorel wrote:
> Changes from v3 (all by Andrea):
>
> * Add setup (alias to .venv)
> * Move sphinx to requirements.txt (therefore remove handling in Makefile)
> * Add support also for fish (csh/tcsh ignored, supporting: fish, bash/zsh)
> * Use 'setup' instead of '.venv' in the top level doc target
>
> NOTE: 'distclean' of doc/ directory is not in the top level directory
> (IMHO not needed).
>
> Are we there yet?
>
> Kind regards,
> Petr
>
> Link to v3:
> https://patchwork.ozlabs.org/project/ltp/list/?series=449828&state=*
> https://lore.kernel.org/ltp/20250324234016.367228-1-pvorel@suse.cz/T/#t
>
> Link to v2:
> https://patchwork.ozlabs.org/project/ltp/list/?series=443894&state=*
> https://lore.kernel.org/ltp/20250211233552.1990618-1-pvorel@suse.cz/#r
>
> Link to v1:
> https://patchwork.ozlabs.org/project/ltp/patch/20250206143421.1571918-4-pvorel@suse.cz/
> https://lore.kernel.org/ltp/20250206143421.1571918-4-pvorel@suse.cz/
>
> Petr Vorel (5):
>    doc/Makefile: Remove also metadata/ltp.json
>    doc: Add sphinx to requirements.txt
>    doc/Makefile: Allow to create and use .venv
>    Makefile: Update 'doc' target, add 'doc-clean'
>    doc: Note 'make doc' in the building doc
>
>   Makefile                         |  8 +++++++-
>   doc/Makefile                     | 25 ++++++++++++++++++++++---
>   doc/developers/documentation.rst |  4 ++--
>   doc/requirements.txt             |  1 +
>   4 files changed, 32 insertions(+), 6 deletions(-)
>

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp