From 31dc0180190f2e00c092b2d38328b51af9c1cda6 Mon Sep 17 00:00:00 2001 From: Martin Renvoize Date: Thu, 15 Jan 2026 15:34:19 +0000 Subject: [PATCH] Bug 41634: Add Pod::Tidy support for consistent POD documentation formatting This integrates Pod::Tidy into Koha's development workflow, similar to how Perl::Tidy handles code formatting. Changes: - Add .podtidyrc configuration file with columns=120 and indent=4 - Update misc/devel/tidy.pl to run podtidy after perltidy on Perl files - Add libpod-tidy-perl to Debian build dependencies - Create xt/podtidy.t test to verify POD formatting - Include .podtidyrc in Makefile.PL distribution manifest Test Plan: 1. Install libpod-tidy-perl dependency 2. Run `./misc/devel/tidy.pl --perl` on Perl files containing POD 3. Verify POD sections are properly formatted (e.g., consistent indentation) 4. Run `prove xt/podtidy.t` to ensure all POD is tidy 5. Commit changes to trigger pre-commit hook which applies tidying automatically --- .podtidyrc | 3 +++ Makefile.PL | 1 + debian/control | 2 ++ misc/devel/tidy.pl | 11 ++++++++++- xt/podtidy.t | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 62 insertions(+), 1 deletion(-) create mode 100644 .podtidyrc create mode 100644 xt/podtidy.t diff --git a/.podtidyrc b/.podtidyrc new file mode 100644 index 00000000000..3af8c4329f6 --- /dev/null +++ b/.podtidyrc @@ -0,0 +1,3 @@ +--columns=120 +--indent=4 +--quiet \ No newline at end of file diff --git a/Makefile.PL b/Makefile.PL index bac08cbd7ba..97d584b4dee 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -350,6 +350,7 @@ my $target_map = { './patroncards' => 'INTRANET_CGI_DIR', './patron_lists' => 'INTRANET_CGI_DIR', './perltidyrc' => 'NONE', + './.podtidyrc' => 'NONE', './plugins' => 'INTRANET_CGI_DIR', './pos' => 'INTRANET_CGI_DIR', './preservation' => 'INTRANET_CGI_DIR', diff --git a/debian/control b/debian/control index 1e137435350..930c7f06c14 100644 --- a/debian/control +++ b/debian/control @@ -121,6 +121,7 @@ Build-Depends: libalgorithm-checkdigits-perl, libplack-middleware-logwarn-perl, libplack-middleware-reverseproxy-perl, libpod-coverage-perl, + libpod-tidy-perl, libreadonly-perl, libscalar-list-utils-perl, libschedule-at-perl, @@ -372,6 +373,7 @@ Depends: libalgorithm-checkdigits-perl, libplack-middleware-logwarn-perl, libplack-middleware-reverseproxy-perl, libpod-coverage-perl, + libpod-tidy-perl, libreadonly-perl, libscalar-list-utils-perl, libschedule-at-perl, diff --git a/misc/devel/tidy.pl b/misc/devel/tidy.pl index f8829044eec..b6146b90d77 100755 --- a/misc/devel/tidy.pl +++ b/misc/devel/tidy.pl @@ -141,6 +141,14 @@ sub tidy_perl { : sprintf q{perltidy --backup-and-modify-in-place --nostandard-output -pro=%s %s}, $perltidyrc, $file; print qx{$cmd}; + + # Run podtidy on the same file + my $pod_cmd = + $no_write + ? sprintf q{podtidy --config=.podtidyrc --stdout %s}, $file + : sprintf q{podtidy --config=.podtidyrc --backup-and-modify-in-place %s}, $file; + + print qx{$pod_cmd}; } sub tidy_js { @@ -197,7 +205,7 @@ sub l { =head1 NAME -tidy.pl - Tidy Perl, Javascript, Vue and Template::Toolkit files. +tidy.pl - Tidy Perl (including POD), Javascript, Vue and Template::Toolkit files. =head1 SYNOPSIS @@ -216,6 +224,7 @@ tidy.pl [options] [files] =head1 DESCRIPTION This script will tidy the different files present in the git repository. +For Perl files, it runs both perltidy (for code formatting) and podtidy (for POD documentation formatting). If the file is an exception and should be tidy, it will be skipped. However if only one file is passed with --no-write then the content of the file will be print to STDOUT. diff --git a/xt/podtidy.t b/xt/podtidy.t new file mode 100644 index 00000000000..79a23832126 --- /dev/null +++ b/xt/podtidy.t @@ -0,0 +1,46 @@ +#!/usr/bin/perl +use Modern::Perl; +use Test::More; +use Test::NoWarnings; +use IPC::Cmd qw(run); +use File::Temp qw(tempfile); +use File::Slurp qw(read_file write_file); + +use Koha::Devel::CI::IncrementalRuns; + +my $ci = Koha::Devel::CI::IncrementalRuns->new( { context => 'tidy' } ); +my @files = $ci->get_files_to_test('pl'); + +plan tests => scalar(@files) + 1; + +my %results; +for my $file (@files) { + ok( is_pod_tidy($file) ) or $results{$file} = 1; +} + +$ci->report_results( \%results ); + +sub is_pod_tidy { + my ($file) = @_; + + # Create a temp file to check tidiness + my ( $fh, $tempfile ) = tempfile(); + write_file( $tempfile, read_file($file) ); + + # Run podtidy on the temp file + my ( $success, $error_message, $full_buf, $stdout_buf, $stderr_buf ) = + run( command => "podtidy --config=.podtidyrc $tempfile" ); + + unless ($success) { + unlink $tempfile; + return 0; # podtidy failed + } + + # Check if the file changed + my $original = read_file($file); + my $tidied = read_file($tempfile); + + unlink $tempfile; + + return $original eq $tidied; +} -- 2.52.0