Publish spec for generic-table-dev branch in CI

chrispsommers commented 1 year ago

generic-table-dev branch will be a long-livid working branch with significant specification additions. To facilitate community participation and review, we should publish this version to GitHub pages along with main. We can do this a couple different ways:

Editing https://github.com/p4lang/p4runtime/blob/generic-table-dev/.github/workflows/main-branch-uploads.yml to add another branch to the trigger conditions (also would need to use variables instead of constants where main is specified in the job steps
Duplicating https://github.com/p4lang/p4runtime/blob/generic-table-dev/.github/workflows/main-branch-uploads.yml and change main to generic-table-dev as appropriate. We can delete the file when this workflow is no longer needed.

Once we get a spec published, we can put a link to it on the main README.

antoninbas commented 1 year ago

Renaming the workflow to something more generic and adding the new branch as a trigger seems like a good idea to me. If you want the spec to be accessible under p4.org, you will need @jnfoster to help you out. He came up with a Javascript-based solution to make it possible. If you're happy with the S3 link, you can just use that directly.

chrispsommers commented 1 year ago

Thanks, Antonin, I can try that. Let's see if @jnfoster has anything to add. Add the workflow and updating the S3 link are separate things which can be in one PR or two.

antoninbas commented 1 year ago

Sorry I wasn't clear. You are already getting a S3 link today: https://s3-us-west-2.amazonaws.com/p4runtime/ci/generic-table-dev/P4Runtime-Spec.html If you update the workflow, you will get another S3 link: https://s3-us-west-2.amazonaws.com/p4runtime/docs/generic-table-dev/P4Runtime-Spec.html (ci/ is replaced with docs/) But in order to get a p4.org link (e.g., https://p4.org/p4-spec/docs/p4runtime-spec-generic-table-dev-html-version.html) to work and point to the version of the spec stored in Github pages, you will need Nate's help (in addition to modifying the workflow).

Note that the version stored in S3 and the version that would be stored in Github pages is the same. So one could argue that https://s3-us-west-2.amazonaws.com/p4runtime/ci/generic-table-dev/P4Runtime-Spec.html is sufficient.

jnfoster commented 1 year ago

Here's what we did for the P4 language spec.

The p4.org web server has these static pages:

p4-16-working-draft.html:

<!DOCTYPE html>
<html>
<head>
<script>
const url = "https://raw.githubusercontent.com/p4lang/p4-spec/gh-pages/docs/P4-16-working-spec.html";  
const req = new XMLHttpRequest();
req.open("GET", url, true);
req.onload = (_) => {
    const doc = document.open("text/html", "replace");
    doc.write( req.response );
    doc.close();
};
req.send(null)
</script>
</head>
<body></body>
</html>

p4-16-working-draft-pdf.html

<!DOCTYPE html>
<html>
<head>
<script>
const url = "https://raw.githubusercontent.com/p4lang/p4-spec/gh-pages/docs/P4-16-working-spec.pdf";
const req = new XMLHttpRequest();
req.open("GET", url, true);
req.responseType = "arraybuffer";
req.onload = (_) => {
  const blob = new Blob([new Uint8Array(req.response)], { type: "application/pdf" });
  var newUrl = URL.createObjectURL(blob);
  window.location.href = newUrl;
};
req.send(null);
</script>
</head>
<body>
</body>
</html>

And there is a script that automatically builds these GitHub Pages-hosted versions on every commit to the main branch of the repository. The only two downsides I see are (1) it relies on JavaScript, and (2) the URL for the PDF becomes a random string made up by the browser. But I'm not losing sleep over either one...

As @antoninbas said, you could shift to GitHub Pages URLs, or just as well use the S3-hosted URLs... it should work either way.

chrispsommers commented 1 year ago

@jnfoster thanks, I'll look into this once we have a spec to publish!

p4lang / p4runtime

Publish spec for generic-table-dev branch in CI #436