|
| 1 | +# Display minutes' information |
| 2 | + |
| 3 | +At the moment, the minutes generated for W3C calls (using the "standard" `scribe` tool) are spread on W3C's date space. Unfortunately, there is no single place where all the minutes could be seen altogether to see their original agenda, or to see the resolutions that have been passed. This small utility is built on top of the standard W3C minutes to make this possible. It relies on the assumption that the list of all minutes can be located via an API and, on top of those it generates two files: |
| 4 | + |
| 5 | +- `index.html`: a file listing all the minutes, grouped by years and the possibility to look at the agenda of all those |
| 6 | +- `resolutions.html`: a file listing all the formal resolutions passed and documented, grouped by years. |
| 7 | + |
| 8 | +The script can be installed in a GitHub repository and can be used to automatically generate those two files in a GitHub page using an action script (see below). |
| 9 | + |
| 10 | +***At the moment*** the only way of using this script is to (manually…) regroup all the minutes in a directory within the GitHub repository and use the GitHub API to access to the minute references. It is hoped that, eventually, there will be a W3C API entry to extract that information (e.g., by accessing the WG Calendar entries). The script should be easily adaptable for new APIs. The script has been developed for the [Publishing Maintenance Working Group](https://www.w3.org/groups/wg/pm) and has been deployed on the [WG repository](https://github.com/w3c/pm-wg). |
| 11 | + |
| 12 | +## Technical details |
| 13 | + |
| 14 | +The script is in typescript, and has been developed and deployed using [deno](https://deno.land). (It is meant to be compatible with [node.js+typescript](https://nodejs.org), though.) It consists of three scripts |
| 15 | + |
| 16 | +- `main.ts`: deploys the information on minutes by filling in the dedicated "slots" in two template files: `templates/index_template.html` and `templates/resolutions_template.html`. The results are stored in the `index.html` and `resolutions.html` files, respectively. Note that the `main.ts` file includes a `const wg = "pm-wg";` declaration referring to a (w3c) repository storing the minutes. This variable should be adapted to another repository, providing that the directory setup is identical. |
| 17 | +- `tools.ts`: set of functions to access, and retrieve, table of content and resolutions from a minute file. It is based on the specificities the minutes files as generated by the standard `scribe` tool. |
| 18 | + |
| 19 | + The file contains the `APIUrl` and `HTMLUrl` strings used to access the API for the minutes and the format |
| 20 | + for the final minute URLs. The first constant also depends on a particular structure of the data in the repository (i.e., the minutes are stored in a `minutes` directory). |
| 21 | + |
| 22 | + Both constats rely, at the moment, on GitHub for the exact format. Those two constants, and the internals of the `getMinutes` method, are GitHub specific, and should be adapted if another API is used. |
| 23 | +- `minidom.ts`: a thin layer on top of the HTML DOM with a few handy shortcut functions. The exact choice of the DOM implementation package is also "hidden" in this module, and can be updated if needed. |
| 24 | + |
| 25 | +### Installation in GitHub pages |
| 26 | + |
| 27 | +The tool can also be used to make the file generation automatic via a GitHub workflow. For reference, here is the workflow used on the aforementioned repository (the GitHub options for `pages` deployment must be set to "GitHub actions"): |
| 28 | + |
| 29 | +```yml |
| 30 | +# Relies on the standard GitHub action setup to deploy to GitHub Pages |
| 31 | +# The really specific details are in the steps that generates the index files |
| 32 | +# (and the deployment of deno as an underling tool). |
| 33 | +name: Publish to Github Pages |
| 34 | +on: |
| 35 | + push: |
| 36 | + branches: [main] |
| 37 | + # Allows workflow to be triggered manually from the Actions tab |
| 38 | + workflow_dispatch: |
| 39 | + |
| 40 | +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages |
| 41 | +permissions: |
| 42 | + contents: read |
| 43 | + pages: write |
| 44 | + id-token: write |
| 45 | + |
| 46 | +# Allow one concurrent deployment |
| 47 | +concurrency: |
| 48 | + group: "pages" |
| 49 | + cancel-in-progress: true |
| 50 | + |
| 51 | +jobs: |
| 52 | + deploy: |
| 53 | + environment: |
| 54 | + name: github-pages |
| 55 | + url: ${{ steps.deployment.outputs.page_url }} |
| 56 | + runs-on: ubuntu-latest |
| 57 | + steps: |
| 58 | + - name: Checkout the repository |
| 59 | + uses: actions/checkout/@v4 |
| 60 | + - name: Setup Deno |
| 61 | + uses: denoland/setup-deno@v2 |
| 62 | + with: |
| 63 | + deno-version: v2.x |
| 64 | + - name: Generate the index files |
| 65 | + # Details depend on where the script is located |
| 66 | + run: | |
| 67 | + (cd script; deno run -A main.ts) |
| 68 | + rm script/deno.lock |
| 69 | + cp script/index.html minutes/index.html |
| 70 | + cp script/resolutions.html minutes/resolutions.html |
| 71 | + - name: Setup Github Pages |
| 72 | + uses: actions/configure-pages@v5 |
| 73 | + - name: Upload artifact |
| 74 | + uses: actions/upload-pages-artifact@v3 |
| 75 | + with: |
| 76 | + # Upload entire repository |
| 77 | + path: '.' |
| 78 | + - name: Deploy to GitHub Pages |
| 79 | + id: deployment |
| 80 | + uses: actions/deploy-pages@v4 |
| 81 | +``` |
| 82 | +
|
| 83 | +--- |
| 84 | +
|
| 85 | +All documents in this Repository are licensed by contributors under the [W3C Software and Document License](https://www.w3.org/Consortium/Legal/copyright-software). |
| 86 | +
|
| 87 | +Ivan Herman, @iherman |
0 commit comments