* [PATCH 2/4] scripts: sphinx-pre-install: add a helper subroutine
2025-06-25 16:22 [PATCH 1/4] scripts: sphinx-pre-install: Add --interactive flag Sai Vishnu M
@ 2025-06-25 16:22 ` Sai Vishnu M
2025-06-25 16:22 ` [PATCH 3/4] scripts: sphinx-pre-install: add fallback to distro detection Sai Vishnu M
` (2 subsequent siblings)
3 siblings, 0 replies; 5+ messages in thread
From: Sai Vishnu M @ 2025-06-25 16:22 UTC (permalink / raw)
To: corbet, mchehab; +Cc: linux-doc, linux-kernel, shuah, 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
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 3/4] scripts: sphinx-pre-install: add fallback to distro detection
2025-06-25 16:22 [PATCH 1/4] scripts: sphinx-pre-install: Add --interactive flag Sai Vishnu M
2025-06-25 16:22 ` [PATCH 2/4] scripts: sphinx-pre-install: add a helper subroutine Sai Vishnu M
@ 2025-06-25 16:22 ` Sai Vishnu M
2025-06-25 16:22 ` [PATCH 4/4] scripts: sphinx-pre-install: Integrate interactive mode Sai Vishnu M
2025-06-25 20:32 ` [PATCH 1/4] scripts: sphinx-pre-install: Add --interactive flag Mauro Carvalho Chehab
3 siblings, 0 replies; 5+ messages in thread
From: Sai Vishnu M @ 2025-06-25 16:22 UTC (permalink / raw)
To: corbet, mchehab; +Cc: linux-doc, linux-kernel, shuah, 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
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 4/4] scripts: sphinx-pre-install: Integrate interactive mode
2025-06-25 16:22 [PATCH 1/4] scripts: sphinx-pre-install: Add --interactive flag Sai Vishnu M
2025-06-25 16:22 ` [PATCH 2/4] scripts: sphinx-pre-install: add a helper subroutine Sai Vishnu M
2025-06-25 16:22 ` [PATCH 3/4] scripts: sphinx-pre-install: add fallback to distro detection Sai Vishnu M
@ 2025-06-25 16:22 ` Sai Vishnu M
2025-06-25 20:32 ` [PATCH 1/4] scripts: sphinx-pre-install: Add --interactive flag Mauro Carvalho Chehab
3 siblings, 0 replies; 5+ messages in thread
From: Sai Vishnu M @ 2025-06-25 16:22 UTC (permalink / raw)
To: corbet, mchehab; +Cc: linux-doc, linux-kernel, shuah, 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
^ permalink raw reply related [flat|nested] 5+ messages in thread* Re: [PATCH 1/4] scripts: sphinx-pre-install: Add --interactive flag
2025-06-25 16:22 [PATCH 1/4] scripts: sphinx-pre-install: Add --interactive flag Sai Vishnu M
` (2 preceding siblings ...)
2025-06-25 16:22 ` [PATCH 4/4] scripts: sphinx-pre-install: Integrate interactive mode Sai Vishnu M
@ 2025-06-25 20:32 ` Mauro Carvalho Chehab
3 siblings, 0 replies; 5+ messages in thread
From: Mauro Carvalho Chehab @ 2025-06-25 20:32 UTC (permalink / raw)
To: Sai Vishnu M; +Cc: corbet, mchehab, linux-doc, linux-kernel, shuah
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
^ permalink raw reply [flat|nested] 5+ messages in thread