Re: Converting yelp-check to Python

[Michael Hill <mdhillca gmail com>]

Hi Shaun,

It works for me so far. I needed to change the http in the creativecommons lines to https.

Mike

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