Re: Converting yelp-check to Python
Michael Hill via gnome-doc-list <[email protected]> Sat, 20 Jun 2020 13:47:52 -0400
| Newsgroups | gmane.comp.gnome.documentation |
|---|---|
| Message-ID | <CAGvW9Wfj6c=KnxUJa9bQxFD_YGwmzHVDPQx_hLDMVyAAFX=ydQ@mail.gmail.com> |
--===============5542986443341475098== Content-Type: multipart/alternative; boundary="00000000000083fcde05a8879c3f" --00000000000083fcde05a8879c3f Content-Type: text/plain; charset="UTF-8" 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 <[email protected]> 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 [email protected]: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 > [email protected] > https://mail.gnome.org/mailman/listinfo/gnome-doc-list > --00000000000083fcde05a8879c3f Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable <div dir=3D"ltr"><div>Hi Shaun,</div><div><br></div><div>It works for me so= far. I needed to change the http in the creativecommons lines to https.</d= iv><div><br></div><div>Mike</div><div><br></div></div><br><div class=3D"gma= il_quote"><div dir=3D"ltr" class=3D"gmail_attr">On Sat, Jun 13, 2020 at 2:0= 1 PM Shaun McCance <<a href=3D"mailto:[email protected]">[email protected]= </a>> wrote:<br></div><blockquote class=3D"gmail_quote" style=3D"margin:= 0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">= Hi all,<br> <br> Over the last couple weekends, I've been working on converting yelp-<br= > check to Python. I've basically hit feature parity (with caveats), and<= br> it's now in git. It hasn't yet replaced yelp-check, but you can tes= t<br> it, and I'd appreciate if you did.<br> <br> First, grab from git:<br> <br> =C2=A0 git clone [email protected]:GNOME/yelp-tools.git<br> <br> Then, anywhere you'd normally call yelp-check, instead call python3<br> with the path to tools/yelp-check.py. For example:<br> <br> =C2=A0 python3 yelp-tools/tools/yelp-check.py links \<br> =C2=A0 =C2=A0 gnome-user-docs/gnome-help/C<br> <br> There are two things that are different:<br> <br> 1. There's no support for DocBook's entityref attributes, because I= <br> didn't see an API in lxml to resolve unparsed entity references, and<br= > honestly I don't think I've ever seen anyone use entityref in my 20= or<br> so years of working with the format.<br> <br> 2. It's considerably more strict about orphans in Mallard sites. This<b= r> probably doesn't affect anybody but me, and the new behavior is<br> arguably more correct.<br> <br> If you've read this far, here's some reasoning behind this change. = When<br> I first wrote yelp-tools, and gnome-doc-utils before that, I tried<br> really really hard to keep its dependencies super low to eliminate<br> barriers to adoption. Building GNOME has a different affair back then.<br> So I wrote in sh and awk, and avoided GNUisms whenever they were<br> pointed out to me. I learned *a lot*.<br> <br> Now we have a build system written in Python. Python is everywhere.<br> Nobody is balking at a tool because it uses Python. Why am I still<br> writing in sh and awk?<br> <br> But also, it's only worth converting if there are advantages going<br> forward. So here they are:<br> <br> * The new Python script is a bajillion times faster.<br> <br> * I can make Ducktype just work without an extra conversion step.<br> <br> * I intend to add a config file parser now, and then:<br> <br> * We'll be able to specify default options for commands.<br> <br> * We'll be able to run multiple checks with a single command.<br> <br> * We'll be able to generate reports, which can be run on CI.<br> <br> * We'll be able to do custom commands, replacing the kind of stuff we<b= r> have now in gnome-help.sct.<br> <br> The last point is worth talking about more. Right now, gnome-help.sct<br> has Schematron rules like this one:<br> <br> =C2=A0 <rule context=3D"mal:page/mal:info"><br> =C2=A0 =C2=A0<assert test=3D"normalize-space(mal:desc) !=3D '&#= 39;"<br> =C2=A0 =C2=A0 >Must have non-empty desc</assert><br> =C2=A0 </rule><br> <br> Not bad, pretty straight-forward. Then you run an xmllint command that<br> you can find in a comment at the top of the file. It works.<br> <br> My plan is that a yelp-check.cfg file can contain this:<br> <br> =C2=A0 [desc-non-empty]<br> =C2=A0 Select =3D /mal:page/mal:info<br> =C2=A0 Assert =3D normalize-space(mal:desc) !=3D ''<br> =C2=A0 Message =3D Must have non-empty desc<br> <br> And then you could run:<br> <br> =C2=A0 yelp-check desc-non-empty<br> <br> Anyway, long email over. Please test the new Python script.<br> <br> Thanks,<br> Shaun<br> <br> <br> <br> <br> <br> _______________________________________________<br> gnome-doc-list mailing list<br> <a href=3D"mailto:[email protected]" target=3D"_blank">gnome-doc-lis= [email protected]</a><br> <a href=3D"https://mail.gnome.org/mailman/listinfo/gnome-doc-list" rel=3D"n= oreferrer" target=3D"_blank">https://mail.gnome.org/mailman/listinfo/gnome-= doc-list</a><br> </blockquote></div> --00000000000083fcde05a8879c3f-- --===============5542986443341475098== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ gnome-doc-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/gnome-doc-list --===============5542986443341475098==--