[PATCH 1/4] scripts: sphinx-pre-install: Add --interactive flag

[PATCH 1/4] scripts: sphinx-pre-install: Add --interactive flag

[Sai Vishnu M]

From: Sai Vishnu M <saivishnu725@gmail.com>

Introduce the --interactive flag to enable prompting for package
installation commands. Add $interactive variable and update the usage
message to include the new flag. Check for terminal input (-t STDIN) to
skip interactive feature in a non-interactive session.

Signed-off-by: Sai Vishnu M <saivishnu725@gmail.com>
---
The RFC proposes 4 patches that will integrate the interactive feature
into the sphinx-pre-install script.
Link: https://lore.kernel.org/linux-doc/CAFttn56VFPjikxjhgds6LjphinStm_cN+7ZhAzsieT0gnBqBDQ@mail.gmail.com/

 scripts/sphinx-pre-install | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index ad9945ccb0cf..6e6e5bda6186 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -42,6 +42,7 @@ my $latest_avail_ver;
 my $pdf = 1;
 my $virtualenv = 1;
 my $version_check = 0;
+my $interactive = 0;
 
 #
 # List of required texlive packages on Fedora and OpenSuse
@@ -1002,12 +1003,18 @@ while (@ARGV) {
 		$pdf = 0;
 	} elsif ($arg eq "--version-check"){
 		$version_check = 1;
+	} elsif ($arg eq "--interactive") {
+		# check if the user can interact with the script
+		if (-t STDIN) {
+			$interactive = 1;
+		}
 	} else {
-		print "Usage:\n\t$0 <--no-virtualenv> <--no-pdf> <--version-check>\n\n";
+		print "Usage:\n\t$0 <--no-virtualenv> <--no-pdf> <--version-check> <--interactive>\n\n";
 		print "Where:\n";
 		print "\t--no-virtualenv\t- Recommend installing Sphinx instead of using a virtualenv\n";
 		print "\t--version-check\t- if version is compatible, don't check for missing dependencies\n";
-		print "\t--no-pdf\t- don't check for dependencies required to build PDF docs\n\n";
+		print "\t--no-pdf\t- don't check for dependencies required to build PDF docs\n";
+		print "\t--interactive\t- ask to install missing dependencies\n\n";
 		exit -1;
 	}
 }
-- 
2.49.0

[PATCH 2/4] scripts: sphinx-pre-install: add a helper subroutine

[Sai Vishnu M]

From: Sai Vishnu M <saivishnu725@gmail.com>

Implement run_if_interactive subroutine to prompt for command execution.
The script crashes if the command fails to execute properly.

Signed-off-by: Sai Vishnu M <saivishnu725@gmail.com>
---
Patch series history:
1 -> implement the --interactive flag

 scripts/sphinx-pre-install | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index 6e6e5bda6186..16eb739fd633 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -339,6 +339,22 @@ sub which($)
 	return undef;
 }
 
+sub run_if_interactive($)
+{
+	my $command = shift;
+	printf("\n\t$command\n");
+
+	if ($interactive) {
+		printf("Run the command now? [Y/n]: ");
+		my $user_input = <STDIN>;
+		chomp $user_input;
+		if ($user_input eq '' or $user_input =~ /^y(es)?$/i) {
+			system($command) == 0
+				or die "Failed to run the command";
+		}
+	}
+}
+
 #
 # Subroutines that check distro-specific hints
 #
-- 
2.49.0

[PATCH 3/4] scripts: sphinx-pre-install: add fallback to distro detection

[Sai Vishnu M]

From: Sai Vishnu M <saivishnu725@gmail.com>

Implement derived_distro_detection to prompt users to select a base
distro in interactive mode for unrecognized distributions. Move the
fallback code for unknown distributions to fallback_unknown_distro.
Update check_distros to use these functions.

Signed-off-by: Sai Vishnu M <saivishnu725@gmail.com>
---
Patch series history:
1 -> implement the --interactive flag
2 -> add run_if_interactive subroutine

Testing:
=========
Tested on a Debian container

Steps taken:
1. Start a container with all files
        podman pull docker.io/debian:bookworm
        mkdir -p /tmp/sphinx-test/Documentation
        cp ./scripts/sphinx-pre-install /tmp/sphinx-test
        cp ./Documentation/conf.py /tmp/sphinx-test/Documentation
        cd /tmp/sphinx-test
        podman run -it --rm -v $(pwd):/work:z debian:bookworm bash

2. Modify /etc/os-release to simulate an unknown distro:
        echo -e 'NAME="UnknownDistro"\nID=unknowndistro' > /etc/os-release
        rm /etc/lsb-release 2>/dev/null

3. Install perl and dependencies
        apt-get update && apt-get install -y perl sudo

4. Run the script in interactive mode
        cd /work; perl sphinx-pre-install --interactive

 scripts/sphinx-pre-install | 63 ++++++++++++++++++++++++++++++--------
 1 file changed, 50 insertions(+), 13 deletions(-)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index 16eb739fd633..e4f8a658857a 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -355,6 +355,51 @@ sub run_if_interactive($)
 	}
 }
 
+sub fallback_unknown_distro()
+{
+	# Fall-back to generic hint code for other distros
+	# That's far from ideal, especially for LaTeX dependencies.
+	my %map = (
+		"sphinx-build" => "sphinx"
+	);
+	check_missing_tex(2) if ($pdf);
+	check_missing(\%map);
+	print "I don't know distro $system_release.\n";
+	print "So, I can't provide you a hint with the install procedure.\n";
+	print "There are likely missing dependencies.\n";
+}
+
+#
+# if the distribution is not recognised
+# but it is derived from the available options
+#
+sub derived_distro_detection()
+{
+	my @distros = (
+		{ name => "Debian/Ubuntu", func => \&give_debian_hints },
+		{ name => "RedHat/CentOS/Fedora", func => \&give_redhat_hints },
+		{ name => "OpenSUSE", func => \&give_opensuse_hints },
+		{ name => "Mageia", func => \&give_mageia_hints },
+		{ name => "Arch Linux", func => \&give_arch_linux_hints },
+		{ name => "Gentoo", func => \&give_gentoo_hints },
+	);
+	print "Which distro is your OS based on?\n";
+	for my $i (0 .. $#distros) {
+		printf("[%d] %s\n", $i + 1, $distros[$i]->{name});
+	}
+	print "[99] Others\n";
+
+	print "Select a number: ";
+	my $choice = <STDIN>;
+	chomp $choice;
+
+	if ($choice =~ /^\d+$/ && $choice >= 1 && $choice <= scalar(@distros)) {
+		$distros[$choice - 1]->{func}->();
+	} else {
+		fallback_unknown_distro();
+	}
+}
+
 #
 # Subroutines that check distro-specific hints
 #
@@ -695,19 +740,11 @@ sub check_distros()
 		give_gentoo_hints;
 		return;
 	}
-
-	#
-	# Fall-back to generic hint code for other distros
-	# That's far from ideal, specially for LaTeX dependencies.
-	#
-	my %map = (
-		"sphinx-build" => "sphinx"
-	);
-	check_missing_tex(2) if ($pdf);
-	check_missing(\%map);
-	print "I don't know distro $system_release.\n";
-	print "So, I can't provide you a hint with the install procedure.\n";
-	print "There are likely missing dependencies.\n";
+	if ( $interactive ) {
+		derived_distro_detection();
+		return;
+	}
+	fallback_unknown_distro();
 }
 
 #
-- 
2.49.0

[PATCH 4/4] scripts: sphinx-pre-install: Integrate interactive mode

[Sai Vishnu M]

From: Sai Vishnu M <saivishnu725@gmail.com>

Replace direct printf calls with run_if_interactive for installation
commands across all distro-specific hint subroutines, enabling user
prompts in interactive mode.

Signed-off-by: Sai Vishnu M <saivishnu725@gmail.com>
---
Patch series history:
1 -> implement the --interactive flag
2 -> add run_if_interactive subroutine
3 -> add fallback to unrecognized distributions

Testing:
========

Tested: Debian, Ubuntu, Fedora, openSUSE Tumbleweed, Mageia.
Skipped: Gentoo (setup complexity but similarity in modification to others)
Steps taken:
1. Podman to download the containers:
	podman pull docker.io/debian:bookworm
	podman pull docker.io/ubuntu:24.04
	podman pull docker.io/fedora:40
	podman pull docker.io/opensuse/tumbleweed:latest
	podman pull docker.io/mageia:9
	podman pull docker.io/gentoo/stage3:latest

2. Copy the script and related files to a temporary folder
	mkdir -p /tmp/sphinx-test/Documentation/
	cp ./scripts/sphinx-pre-install /tmp/sphinx-test
	cp ./Documentation/conf.py /tmp/sphinx-test/Documentation
	cd /tmp/sphinx-test

3. Connect to the containers
	podman run -it --rm -v $(pwd):/work:z CONTAINER:VERSION bash
	Ex: podman run -it --rm -v $(pwd):/work:z debian:bookworm bash
	
4. Install perl and dependencies
	# Debian/Ubuntu
	apt-get update && apt-get install -y perl sudo
	# Fedora
	dnf install -y perl sudo
	# OpenSUSE
	zypper install -y perl sudo
	# Mageia
	dnf install -y perl sudo
	# Gentoo (requires more setup)
	emerge-webrsync && emerge dev-lang/perl

5. Run the script
	a. Interactive
		cd /work; perl sphinx-pre-install --interactive
	b. Non Interactive
		cd /work; perl sphinx-pre-install

 scripts/sphinx-pre-install | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index 87eef15650f2..c2e10170e6c1 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -436,7 +436,8 @@ sub give_debian_hints()
 
 	return if (!$need && !$optional);
 	printf("You should run:\n") if ($verbose_warn_install);
-	printf("\n\tsudo apt-get install $install\n");
+	my $command = "sudo apt-get install $install";
+	run_if_interactive($command);
 }
 
 sub give_redhat_hints()
@@ -514,11 +515,13 @@ sub give_redhat_hints()
 	if (!$old) {
 		# dnf, for Fedora 18+
 		printf("You should run:\n") if ($verbose_warn_install);
-		printf("\n\tsudo dnf install -y $install\n");
+		my $command = "sudo dnf install -y $install";
+		run_if_interactive($command);
 	} else {
 		# yum, for RHEL (and clones) or Fedora version < 18
 		printf("You should run:\n") if ($verbose_warn_install);
-		printf("\n\tsudo yum install -y $install\n");
+		my $command = "sudo yum install -y $install";
+		run_if_interactive($command);
 	}
 }
 
@@ -567,7 +570,8 @@ sub give_opensuse_hints()
 
 	return if (!$need && !$optional);
 	printf("You should run:\n") if ($verbose_warn_install);
-	printf("\n\tsudo zypper install --no-recommends $install\n");
+	my $command = "sudo zypper install --no-recommends $install";
+	run_if_interactive($command);
 }
 
 sub give_mageia_hints()
@@ -612,7 +616,8 @@ sub give_mageia_hints()
 
 	return if (!$need && !$optional);
 	printf("You should run:\n") if ($verbose_warn_install);
-	printf("\n\tsudo $packager_cmd $install\n");
+	my $command = "sudo $packager_cmd $install";
+	run_if_interactive($command);
 }
 
 sub give_arch_linux_hints()
@@ -643,7 +648,8 @@ sub give_arch_linux_hints()
 
 	return if (!$need && !$optional);
 	printf("You should run:\n") if ($verbose_warn_install);
-	printf("\n\tsudo pacman -S $install\n");
+	my $command = "sudo pacman -S $install";
+	run_if_interactive($command);
 }
 
 sub give_gentoo_hints()
@@ -679,13 +685,16 @@ sub give_gentoo_hints()
 	my $portage_cairo = "/etc/portage/package.use/graphviz";
 
 	if (qx(grep imagemagick $portage_imagemagick 2>/dev/null) eq "") {
-		printf("\tsudo su -c 'echo \"$imagemagick\" > $portage_imagemagick'\n")
+		my $imagemagick_command = "sudo su -c 'echo \"$imagemagick\" > $portage_imagemagick'";
+		run_if_interactive($imagemagick_command);
 	}
 	if (qx(grep graphviz $portage_cairo 2>/dev/null) eq  "") {
-		printf("\tsudo su -c 'echo \"$cairo\" > $portage_cairo'\n");
+		my $portage_command = "sudo su -c 'echo \"$cairo\" > $portage_cairo'";
+		run_if_interactive($portage_command);
 	}
 
-	printf("\tsudo emerge --ask $install\n");
+	my $command = "sudo emerge --ask $install";
+	run_if_interactive($command);
 
 }
 
-- 
2.49.0

Re: [PATCH 1/4] scripts: sphinx-pre-install: Add --interactive flag

[Mauro Carvalho Chehab]

Em Wed, 25 Jun 2025 21:52:34 +0530
Sai Vishnu M <saivishnu725@gmail.com> escreveu:

> From: Sai Vishnu M <saivishnu725@gmail.com>
> 
> Introduce the --interactive flag to enable prompting for package
> installation commands. Add $interactive variable and update the usage
> message to include the new flag. Check for terminal input (-t STDIN) to
> skip interactive feature in a non-interactive session.
> 
> Signed-off-by: Sai Vishnu M <saivishnu725@gmail.com>

Hi Sai/Jon,

FYI, I'm currently working on porting this script to Python. I have
already an experimental code here, but the hardest part is to test
it on all supported distros ;-)

My initial version is aiming on support the distros below, provided
that I can succeed installing a container with lxc or podman, and
run regression tests on all distros via scripts:

    def check_distros(self):
        # OS-specific hints logic
        os_hints = {
            re.compile("Red Hat Enterprise Linux"): self.give_redhat_hints,
            re.compile("CentOS"):                   self.give_redhat_hints,
            re.compile("Scientific Linux"):         self.give_redhat_hints,
            re.compile("Oracle Linux Server"):      self.give_redhat_hints,
            re.compile("Fedora"):                   self.give_redhat_hints,

            re.compile("Ubuntu"):                   self.give_debian_hints,
            re.compile("Debian"):                   self.give_debian_hints,
            re.compile("Mint"):                     self.give_debian_hints,

            re.compile("openSUSE"):                 self.give_opensuse_hints,

            re.compile("Mageia"):                   self.give_mageia_hints,
            re.compile("OpenMandriva"):             self.give_mageia_hints,

            re.compile("Arch Linux"):               self.give_arch_linux_hints,
            re.compile("Gentoo"):                   self.give_gentoo_hints,
        }

        # If the OS is detected, use per-OS hint logic
        for regex, os_hint in os_hints.items():
            if regex.search(self.system_release):
                os_hint()

                return

I just succeeded installing on Mageia via docker, as it doesn't have lxc.
As always, Gentoo is still a challenge. The same applies to some RHEL-based
distros that require cgroups-v1.

Anyway, if everything goes well, I'll have it ready along this week.

For the port, I'm aiming to have a bug-compatible version
with the Perl one, but adding support to install can be a nice
addition (eventually with the messages sorted, as I'm planning
to sort the install requirements).

---

One general comment on this series: you're splitting one logical
change into multiple patches, starting from the command line parser.
The best is to merge the change on a more atomic way, avoiding
potential git bisect breakages.

> ---
> The RFC proposes 4 patches that will integrate the interactive feature
> into the sphinx-pre-install script.
> Link: https://lore.kernel.org/linux-doc/CAFttn56VFPjikxjhgds6LjphinStm_cN+7ZhAzsieT0gnBqBDQ@mail.gmail.com/
> 
>  scripts/sphinx-pre-install | 11 +++++++++--
>  1 file changed, 9 insertions(+), 2 deletions(-)
> 
> diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
> index ad9945ccb0cf..6e6e5bda6186 100755
> --- a/scripts/sphinx-pre-install
> +++ b/scripts/sphinx-pre-install
> @@ -42,6 +42,7 @@ my $latest_avail_ver;
>  my $pdf = 1;
>  my $virtualenv = 1;
>  my $version_check = 0;
> +my $interactive = 0;
>  
>  #
>  # List of required texlive packages on Fedora and OpenSuse
> @@ -1002,12 +1003,18 @@ while (@ARGV) {
>  		$pdf = 0;
>  	} elsif ($arg eq "--version-check"){
>  		$version_check = 1;
> +	} elsif ($arg eq "--interactive") {
> +		# check if the user can interact with the script
> +		if (-t STDIN) {
> +			$interactive = 1;
> +		}
>  	} else {
> -		print "Usage:\n\t$0 <--no-virtualenv> <--no-pdf> <--version-check>\n\n";
> +		print "Usage:\n\t$0 <--no-virtualenv> <--no-pdf> <--version-check> <--interactive>\n\n";
>  		print "Where:\n";
>  		print "\t--no-virtualenv\t- Recommend installing Sphinx instead of using a virtualenv\n";
>  		print "\t--version-check\t- if version is compatible, don't check for missing dependencies\n";
> -		print "\t--no-pdf\t- don't check for dependencies required to build PDF docs\n\n";
> +		print "\t--no-pdf\t- don't check for dependencies required to build PDF docs\n";
> +		print "\t--interactive\t- ask to install missing dependencies\n\n";
>  		exit -1;
>  	}
>  }



Thanks,
Mauro