Re: docs: automarkup.py

[Mauro Carvalho Chehab <mchehab@kernel.org>]

Em Thu, 28 Dec 2023 12:01:00 -0800
Randy Dunlap <rdunlap@infradead.org> escreveu:

> On 12/28/23 08:22, Mauro Carvalho Chehab wrote:
> > Em Wed, 27 Dec 2023 14:20:05 -0800
> > Randy Dunlap <rdunlap@infradead.org> escreveu:
> >   
> >> Hi Vegard and Mauro,
> >>
> >> Thanks for your assistance.
> >> (more below)
> >>
> >>
> >> On 12/27/23 01:08, Vegard Nossum wrote:  
> >>>
> >>> On 27/12/2023 08:55, Randy Dunlap wrote:    
> >>>> Can anyone explain this?  maybe even suggest a fix for it?
> >>>>
> >>>> This has been around for a few weeks AFAIK. I haven't see a patch for it,
> >>>> but I could have missed it.
> >>>>
> >>>> (since 17e02586ed185 in August/2023; oh, that just fixed the move
> >>>> of files to the Documentation/arch/ subdir, so maybe even longer)
> >>>>
> >>>>
> >>>> In file Documentation/ABI/testing/sysfs-bus-papr-pmem:
> >>>>
> >>>>         response to H_SCM_HEALTH hcall. The details of the bit
> >>>>         flags returned in response to this hcall is available
> >>>>         at 'Documentation/arch/powerpc/papr_hcalls.rst'. Below are
> >>>>         the flags reported in this sysfs file:
> >>>>
> >>>> kernel-doc reports:
> >>>>
> >>>> linux-next-20231222/Documentation/ABI/testing/sysfs-bus-papr-pmem:2: WARNING: unknown document: '/powerpc/papr_hcalls'
> >>>>
> >>>> and the output file Documentation/output/admin-guide/abi-testing.html says:
> >>>>
> >>>> response to H_SCM_HEALTH hcall. The details of the bit
> >>>> flags returned in response to this hcall is available
> >>>> at '<span class="xref std std-doc">/powerpc/papr_hcalls</span>' . Below are
> >>>> the flags reported in this sysfs file:</p>
> >>>>
> >>>>
> >>>> so the leading "Documentation/arch" is being removed from the filename
> >>>> AFAICT.
> >>>>
> >>>> I tried changing the quoted filename from single quotes to double back quotes
> >>>> `` and I tried it without any quotes, all with the same results.
> >>>>    
> >>>
> >>> I don't see that here, there is no warning and it renders properly.
> >>>
> >>> If you go on https://docs.kernel.org/admin-guide/abi-testing.html then
> >>> it says 6.7.0-rc7 and (AFAICT) it also links/renders properly.    
> >>
> >> Yes, I probably should have checked there earlier. :)
> >>  
> >>> Maybe try building in a fresh clone/worktree just to verify there isn't
> >>> some old file somewhere that didn't get cleaned out/updated?    
> >>
> >> That does work but it made me suspicious.
> >>
> >> I was building in a kernel tree that was built from a tarball
> >> and linux-next daily patches.  That leaves behind some *.orig files
> >> (since I use 'patch -b' for "backups").
> >>
> >> If I remove the Documentation/ABI/*.orig files, there is no issue
> >> like I had erroneously reported here.
> >> Maybe get_abi.pl is (also) processing the *.orig files and that
> >> somehow causes it to produce the confusing output.  
> > 
> > The logic which parse files at get_abi.pl is this one:
> > 
> >     sub parse_abi {
> >         my $file = $File::Find::name;
> > 
> >         my $mode = (stat($file))[2];
> >         return if ($mode & S_IFDIR);
> >         return if ($file =~ m,/README,);
> > 
> > Currently, it ignores just README and directories.
> > 
> > It wouldn't be hard to add something like:
> > 
> > 	return if ($file =~ m,/\.(rej|org|orig|bak)$,);  
> 
> That didn't quite work as is. I changed it to this:
> 
> +       return if ($file =~ m,\.(rej|org|orig|bak)$,);
> 
> which works (dropping the leading "/").

Great! If you want, feel free to submit a patch with that with
my Acked-by.

> 
> > to ignore certain extensions. On such case, we would need to explicitly
> > add the extensions to be Ignored.
> > 
> > We could, instead, do a broader regex:
> > 
> > 	return if ($file =~ m,/\.,);  
> 
> That line is already present in the script, for skipping
> hidden (dot) files.
> 
> It does not skip filenames like "papr_hcalls.orig" -- at least I
> still see this problem when that line is present.
> 
> I wouldn't suggest skipping any file that has a '.' in its name.

Yeah, agreed.

Regards,
Mauro