Re: Converting yelp-check to Python

[Shaun McCance <shaunm gnome org>]

On Sat, 2020-06-20 at 13:47 -0400, Michael Hill via gnome-doc-list
wrote:
> Hi Shaun,
>
> It works for me so far. I needed to change the http in the
> creativecommons lines to https.

Thanks for pointing that out. We should add those, as well as any other
URIs people are commonly using for licenses.

All, the Python script has a safelist of common license URIs that it
doesn't even bother checking when running `hrefs`.

https://gitlab.gnome.org/GNOME/yelp-tools/-/blob/master/tools/yelp-check.py#L193

If you have license URIs to add, submit a merge request, file an issue,
or just let me know.


> On Sat, Jun 13, 2020 at 2:01 PM Shaun McCance <shaunm gnome org>
> wrote:
> > Hi all,
> >
> > Over the last couple weekends, I've been working on converting
> > yelp-
> > check to Python. I've basically hit feature parity (with caveats),
> > and
> > it's now in git. It hasn't yet replaced yelp-check, but you can
> > test
> > it, and I'd appreciate if you did.
> >
> > First, grab from git:
> >
> >   git clone git gitlab gnome org:GNOME/yelp-tools.git
> >
> > Then, anywhere you'd normally call yelp-check, instead call python3
> > with the path to tools/yelp-check.py. For example:
> >
> >   python3 yelp-tools/tools/yelp-check.py links \
> >     gnome-user-docs/gnome-help/C
> >
> > There are two things that are different:
> >
> > 1. There's no support for DocBook's entityref attributes, because I
> > didn't see an API in lxml to resolve unparsed entity references,
> > and
> > honestly I don't think I've ever seen anyone use entityref in my 20
> > or
> > so years of working with the format.
> >
> > 2. It's considerably more strict about orphans in Mallard sites.
> > This
> > probably doesn't affect anybody but me, and the new behavior is
> > arguably more correct.
> >
> > If you've read this far, here's some reasoning behind this change.
> > When
> > I first wrote yelp-tools, and gnome-doc-utils before that, I tried
> > really really hard to keep its dependencies super low to eliminate
> > barriers to adoption. Building GNOME has a different affair back
> > then.
> > So I wrote in sh and awk, and avoided GNUisms whenever they were
> > pointed out to me. I learned *a lot*.
> >
> > Now we have a build system written in Python. Python is everywhere.
> > Nobody is balking at a tool because it uses Python. Why am I still
> > writing in sh and awk?
> >
> > But also, it's only worth converting if there are advantages going
> > forward. So here they are:
> >
> > * The new Python script is a bajillion times faster.
> >
> > * I can make Ducktype just work without an extra conversion step.
> >
> > * I intend to add a config file parser now, and then:
> >
> > * We'll be able to specify default options for commands.
> >
> > * We'll be able to run multiple checks with a single command.
> >
> > * We'll be able to generate reports, which can be run on CI.
> >
> > * We'll be able to do custom commands, replacing the kind of stuff
> > we
> > have now in gnome-help.sct.
> >
> > The last point is worth talking about more. Right now, gnome-
> > help.sct
> > has Schematron rules like this one:
> >
> >   <rule context="mal:page/mal:info">
> >    <assert test="normalize-space(mal:desc) != ''"
> >     >Must have non-empty desc</assert>
> >   </rule>
> >
> > Not bad, pretty straight-forward. Then you run an xmllint command
> > that
> > you can find in a comment at the top of the file. It works.
> >
> > My plan is that a yelp-check.cfg file can contain this:
> >
> >   [desc-non-empty]
> >   Select = /mal:page/mal:info
> >   Assert = normalize-space(mal:desc) != ''
> >   Message = Must have non-empty desc
> >
> > And then you could run:
> >
> >   yelp-check desc-non-empty
> >
> > Anyway, long email over. Please test the new Python script.
> >
> > Thanks,
> > Shaun
> >
> >
> >
> >
> >
> > _______________________________________________
> > gnome-doc-list mailing list
> > gnome-doc-list gnome org
> > https://mail.gnome.org/mailman/listinfo/gnome-doc-list
>
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> https://mail.gnome.org/mailman/listinfo/gnome-doc-list