Automating generation of static documents on github

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

Automating generation of static documents on github

Shane McCarron
I know that many of you think that having the editor's drafts rely upon ReSpec is okay, but we get complaints from users who rely upon assistive technologies that it is unacceptable / unworkable for them.  The PFWG has been using gh-pages to present static versions of documents, but has been generating them by hand.  Can anyone suggest a convenient way, maybe using Travis, to automate generation of a static gh-pages version when the master is updated?

--
Shane McCarron
Managing Director, Applied Testing and Technology, Inc.
Reply | Threaded
Open this post in threaded view
|

Re: Automating generation of static documents on github

Robin Berjon-6
On 23/03/2015 14:17 , Shane McCarron wrote:
> I know that many of you think that having the editor's drafts rely upon
> ReSpec is okay, but we get complaints from users who rely upon assistive
> technologies that it is unacceptable / unworkable for them.

Do you have specific issues that you reckon could be fixed there?

> The PFWG
> has been using gh-pages to present static versions of documents, but has
> been generating them by hand.  Can anyone suggest a convenient way,
> maybe using Travis, to automate generation of a static gh-pages version
> when the master is updated?

Generating static versions isn't hard, for instance stuff on
https://specs.webplatform.org/ is commonly ReSpec in the static output.

In terms of automation Travis is indeed probably your best bet. If you
search you'll find plenty of examples. Perhaps the simplest (that I've
seen) is this one:
https://medium.com/@nthgergo/publishing-gh-pages-with-travis-ci-53a8270e87db.

Note that you don't even have to use some locally-installed ReSpec
tooling with Travis, you can use the spec-generator service, e.g.:
https://labs.w3.org/spec-generator/?type=respec&url=https://w3c.github.io/linkToYourSpec/?specStatus=WD;shortName=theShortName

The output from that is the generated spec.

--
Robin Berjon - http://berjon.com/ - @robinberjon

Reply | Threaded
Open this post in threaded view
|

Re: Automating generation of static documents on github

Shane McCarron


On Mon, Mar 23, 2015 at 8:53 AM, Robin Berjon <[hidden email]> wrote:
On 23/03/2015 14:17 , Shane McCarron wrote:
I know that many of you think that having the editor's drafts rely upon
ReSpec is okay, but we get complaints from users who rely upon assistive
technologies that it is unacceptable / unworkable for them.

Do you have specific issues that you reckon could be fixed there?

Maybe.  I have asked for some guidance.  My understanding is that the basic problem is mutation events.  And since there are A LOT of them, it becomes challenging for the user.  Maybe there is some event we can throw upon completion that would clue in the ATs that the document is actually ready.
 


The PFWG
has been using gh-pages to present static versions of documents, but has
been generating them by hand.  Can anyone suggest a convenient way,
maybe using Travis, to automate generation of a static gh-pages version
when the master is updated?

Generating static versions isn't hard, for instance stuff on https://specs.webplatform.org/ is commonly ReSpec in the static output.

In terms of automation Travis is indeed probably your best bet. If you search you'll find plenty of examples. Perhaps the simplest (that I've seen) is this one: https://medium.com/@nthgergo/publishing-gh-pages-with-travis-ci-53a8270e87db.

 

Note that you don't even have to use some locally-installed ReSpec tooling with Travis, you can use the spec-generator service, e.g.: https://labs.w3.org/spec-generator/?type=respec&url=https://w3c.github.io/linkToYourSpec/?specStatus=WD;shortName=theShortName

The output from that is the generated spec.


Huh.  When I try this with https://labs.w3.org/spec-generator/?type=respec&url=http://w3c.github.io/aria/aria/aria.html I get an error that the processor timed out.  But I will look into it!  Thanks again. 



--
Shane McCarron
Managing Director, Applied Testing and Technology, Inc.
Reply | Threaded
Open this post in threaded view
|

Re: Automating generation of static documents on github

Robin Berjon-6
On 23/03/2015 15:23 , Shane McCarron wrote:
> On Mon, Mar 23, 2015 at 8:53 AM, Robin Berjon <[hidden email]
>     Do you have specific issues that you reckon could be fixed there?
>
> Maybe.  I have asked for some guidance.  My understanding is that the
> basic problem is mutation events.  And since there are A LOT of them, it
> becomes challenging for the user.  Maybe there is some event we can
> throw upon completion that would clue in the ATs that the document is
> actually ready.

This seems like a problem that could be relatively common with pages
that load lots of external information and process it progressively.


>     Note that you don't even have to use some locally-installed ReSpec
>     tooling with Travis, you can use the spec-generator service, e.g.:
>     https://labs.w3.org/spec-__generator/?type=respec&url=__https://w3c.github.io/__linkToYourSpec/?specStatus=WD;__shortName=theShortName
>     <https://labs.w3.org/spec-generator/?type=respec&url=https://w3c.github.io/linkToYourSpec/?specStatus=WD;shortName=theShortName>
>
>     The output from that is the generated spec.
>
>
> Huh.  When I try this with
> https://labs.w3.org/spec-generator/?type=respec&url=http://w3c.github.io/aria/aria/aria.html
> I get an error that the processor timed out.  But I will look into it!

That's not a ReSpec document; it's the generated version. The script is
timing out likely because it is never getting the end-all event.

At any rate you would probably have to tackle on
?specStatus=WD;shortName=wai-aria-1.1 at the end there; the
spec-generator needs that to find the previous version and generate the
right parameters for you.


--
Robin Berjon - http://berjon.com/ - @robinberjon

Reply | Threaded
Open this post in threaded view
|

Re: Automating generation of static documents on github

Shane McCarron


On Mon, Mar 23, 2015 at 9:31 AM, Robin Berjon <[hidden email]> wrote:
On 23/03/2015 15:23 , Shane McCarron wrote:
On Mon, Mar 23, 2015 at 8:53 AM, Robin Berjon <[hidden email]
    Do you have specific issues that you reckon could be fixed there?

Maybe.  I have asked for some guidance.  My understanding is that the
basic problem is mutation events.  And since there are A LOT of them, it
becomes challenging for the user.  Maybe there is some event we can
throw upon completion that would clue in the ATs that the document is
actually ready.

This seems like a problem that could be relatively common with pages that load lots of external information and process it progressively.


    Note that you don't even have to use some locally-installed ReSpec
    tooling with Travis, you can use the spec-generator service, e.g.:
    https://labs.w3.org/spec-__generator/?type=respec&url=__https://w3c.github.io/__linkToYourSpec/?specStatus=WD;__shortName=theShortName
    <https://labs.w3.org/spec-generator/?type=respec&url=https://w3c.github.io/linkToYourSpec/?specStatus=WD;shortName=theShortName>

    The output from that is the generated spec.


Huh.  When I try this with
https://labs.w3.org/spec-generator/?type=respec&url=http://w3c.github.io/aria/aria/aria.html
I get an error that the processor timed out.  But I will look into it!

That's not a ReSpec document; it's the generated version. The script is timing out likely because it is never getting the end-all event.

Duh.  Okay I will try it with a raw document.  
 

At any rate you would probably have to tackle on ?specStatus=WD;shortName=wai-aria-1.1 at the end there; the spec-generator needs that to find the previous version and generate the right parameters for you.


 I guess.  But my parameters are embedded in the document already and the spec-generator service says the only required parameters are the type and url.


--
Shane McCarron
Managing Director, Applied Testing and Technology, Inc.
Reply | Threaded
Open this post in threaded view
|

Re: Automating generation of static documents on github

Robin Berjon-6
On 23/03/2015 15:53 , Shane McCarron wrote:
>   I guess.  But my parameters are embedded in the document already and
> the spec-generator service says the only required parameters are the
> type and url.

It lies :)

--
Robin Berjon - http://berjon.com/ - @robinberjon

Reply | Threaded
Open this post in threaded view
|

Re: Automating generation of static documents on github

Shane McCarron
Interesting.  So does it use the respecConfig in the document at all?

On Mon, Mar 23, 2015 at 9:54 AM, Robin Berjon <[hidden email]> wrote:
On 23/03/2015 15:53 , Shane McCarron wrote:
  I guess.  But my parameters are embedded in the document already and
the spec-generator service says the only required parameters are the
type and url.

It lies :)


--
Robin Berjon - http://berjon.com/ - @robinberjon



--
Shane McCarron
Managing Director, Applied Testing and Technology, Inc.
Reply | Threaded
Open this post in threaded view
|

Re: Automating generation of static documents on github

Robin Berjon-6
On 23/03/2015 16:56 , Shane McCarron wrote:
> Interesting.  So does it use the respecConfig in the document at all?

As much as possible. But there's a chicken and egg problem. The
spec-generator is essentially meant to be used with Echidna, which means
it needs to override the previousPublishDate upon generation. In order
to find that, it needs the shortName so it can look it up.

This requirement is likely to be lifted for other users as the
spec-generator is made more generic. It is also likely that ReSpec will
gain the ability to automatically set previousPublishDate and
previousMaturity itself, but that will have to wait until this
information is exposed in a format more usable than a big RDF dump.

--
Robin Berjon - http://berjon.com/ - @robinberjon

Reply | Threaded
Open this post in threaded view
|

Re: Automating generation of static documents on github

Tab Atkins Jr.
In reply to this post by Robin Berjon-6
On Mon, Mar 23, 2015 at 6:53 AM, Robin Berjon <[hidden email]> wrote:
> Generating static versions isn't hard, for instance stuff on
> https://specs.webplatform.org/ is commonly ReSpec in the static output.

Note that https://specs.webplatform.org/ is Bikeshed, actually.  The
three specs under it do appear to be static output of ReSpec, though.

(I'll respectfully note that using Bikeshed is another way to get good
static output, as it's purely server-side from the get-go. ^_^)

~TJ

Reply | Threaded
Open this post in threaded view
|

Re: Automating generation of static documents on github

Robin Berjon-6
On 25/03/2015 22:52 , Tab Atkins Jr. wrote:
> On Mon, Mar 23, 2015 at 6:53 AM, Robin Berjon <[hidden email]> wrote:
>> Generating static versions isn't hard, for instance stuff on
>> https://specs.webplatform.org/ is commonly ReSpec in the static output.
>
> Note that https://specs.webplatform.org/ is Bikeshed, actually.  The
> three specs under it do appear to be static output of ReSpec, though.

I'm not sure what you mean here Tab :) The index page there is neither
ReSpec nor Bikeshed, it's custom-generated. Of the specs there, I
believe one is Bikeshed, the others are ReSpec. The system supports both.

--
Robin Berjon - http://berjon.com/ - @robinberjon

Reply | Threaded
Open this post in threaded view
|

Re: Automating generation of static documents on github

Tab Atkins Jr.
On Thu, Mar 26, 2015 at 3:01 AM, Robin Berjon <[hidden email]> wrote:

> On 25/03/2015 22:52 , Tab Atkins Jr. wrote:
>>
>> On Mon, Mar 23, 2015 at 6:53 AM, Robin Berjon <[hidden email]> wrote:
>>>
>>> Generating static versions isn't hard, for instance stuff on
>>> https://specs.webplatform.org/ is commonly ReSpec in the static output.
>>
>>
>> Note that https://specs.webplatform.org/ is Bikeshed, actually.  The
>> three specs under it do appear to be static output of ReSpec, though.
>
>
> I'm not sure what you mean here Tab :) The index page there is neither
> ReSpec nor Bikeshed, it's custom-generated. Of the specs there, I believe
> one is Bikeshed, the others are ReSpec. The system supports both.

I just checked the source of <https://specs.webplatform.org/>, and it
bears the fingerprint of Bikeshed - the headings, for example, have a
.settled class, and <span class=content> and <a class=self-link>
children.  Unless someone is *very carefully* reproducing all of
Bikeshed's quirks, it's definitely a Bikeshed-processed document.

I hadn't checked all of the specs listed in the index when I made my
earlier statement, only the Markup ones.  The URL one is indeed
Bikeshed, but the other four are ReSpec.

~TJ

Reply | Threaded
Open this post in threaded view
|

Re: Automating generation of static documents on github

Robin Berjon-6
On 26/03/2015 17:23 , Tab Atkins Jr. wrote:

> On Thu, Mar 26, 2015 at 3:01 AM, Robin Berjon <[hidden email]> wrote:
>> I'm not sure what you mean here Tab :) The index page there is neither
>> ReSpec nor Bikeshed, it's custom-generated. Of the specs there, I believe
>> one is Bikeshed, the others are ReSpec. The system supports both.
>
> I just checked the source of <https://specs.webplatform.org/>, and it
> bears the fingerprint of Bikeshed - the headings, for example, have a
> .settled class, and <span class=content> and <a class=self-link>
> children.  Unless someone is *very carefully* reproducing all of
> Bikeshed's quirks, it's definitely a Bikeshed-processed document.

I can *absolutely* assure you that it is not Bikeshed. I hate an
argument from authority just as much as the next folks but given that I
wrote that code I think I can make that statement with a modicum of
confidence.

You do note correctly that a number of Bikeshed quirks are followed.
There's a reason for that: the stylesheet was initially designed to work
with Bikeshed documents. It was easier to get the markup to match that
than to rewrite it.

--
Robin Berjon - http://berjon.com/ - @robinberjon

Reply | Threaded
Open this post in threaded view
|

Re: Automating generation of static documents on github

Tab Atkins Jr.
On Thu, Mar 26, 2015 at 9:36 AM, Robin Berjon <[hidden email]> wrote:

> On 26/03/2015 17:23 , Tab Atkins Jr. wrote:
>> On Thu, Mar 26, 2015 at 3:01 AM, Robin Berjon <[hidden email]> wrote:
>>> I'm not sure what you mean here Tab :) The index page there is neither
>>> ReSpec nor Bikeshed, it's custom-generated. Of the specs there, I believe
>>> one is Bikeshed, the others are ReSpec. The system supports both.
>>
>> I just checked the source of <https://specs.webplatform.org/>, and it
>> bears the fingerprint of Bikeshed - the headings, for example, have a
>> .settled class, and <span class=content> and <a class=self-link>
>> children.  Unless someone is *very carefully* reproducing all of
>> Bikeshed's quirks, it's definitely a Bikeshed-processed document.
>
> I can *absolutely* assure you that it is not Bikeshed. I hate an argument
> from authority just as much as the next folks but given that I wrote that
> code I think I can make that statement with a modicum of confidence.
>
> You do note correctly that a number of Bikeshed quirks are followed. There's
> a reason for that: the stylesheet was initially designed to work with
> Bikeshed documents. It was easier to get the markup to match that than to
> rewrite it.

Hahaha, all right, you win.

~TJ