Re: Converting yelp-check to Python



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



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]