Update the build pipeline

[dmint789]

This is a big PR, but this was a very important update for us to make. It should improve the developer experience greatly when it comes to building the PDFs to see a preview of the documents, which was previously only really easy to do by creating a PR and waiting for the Github pipeline to do it, which always took a while and made it harder to iterate with minor adjustments. This PR does the following:

• Update the build script to use weasyprint instead of wkhtmltopdf, which is no longer maintained and causes bugs in the output PDFs sometimes. Some other minor improvements to this script have also been made.
• Add a new build script that uses Docker for consistent file rendering.
• Unify the duplicated styles between the documents and edudoc stylesheets, and keep the directory-specific styles in their own separate files: documents-style.css and edudoc-style.css
• Make minor adjustments to the documents themselves to ensure there are no alignment issues and to make some of the Markdown look cleaner.
• Renumber points 5. and 6. of the WCA Bylaws section 2.4 as 4. and 5. respectively (point 4. was missing). Keep in mind that it's displayed as 1-5 in production rn, because Markdown seems to ignore what number you actually put there and simply uses the correct one in order.

[nsilvestri]

Inconsistencies noticed:

1. Slight stylistic differences: spacing between lines in particular. Causes some paragraphs to move to other pages.
2. Styling on example email usage in Staff Crash Course

Document issues:

The only issue I found was that on some bullet points and numbers, the bullet/number is on a line above the text for that bullet/number. Non-exhaustive examples are:

• Bylaws doc: 2.4, point 5
• WCRP Announcement Criteria 1., 1.11, 2.5.4.1
• Competitor tutorial, Important Definitions

[dmint789]

@nsilvestri could you provide an example of an unwanted page break due to the spacing between lines? For me the spacing looks the same as it does in production rn.

[dmint789]

Staff crash course fixed

[nsilvestri]

@dmint789 the page breaks caused by spacing are not "unwanted", just slightly different. 1-2 lines will be pushed to the next page, or vice versa. Very minor stylistic thing, just noting it as an inconsistency.

[dmint789]

Fixed the bullet point issue in the competitor tutorial

[dmint789]

Okay, now I need to update the Github actions. I think I've fixed all of the issues you found.

[dmint789]

Found another issue: the counters reset when there is content between two items (see the competition templates doc for an example). Currently working on fixing this.

[dmint789]

Fixed

[dmint789]

I have personally gone through every single markdown document in the repository, fixed all alignment issues and made sure they all look almost exactly the same as the original docs rendered with wkhtmltopdf. The PR is now ready for review.

@nsilvestri could you please review the changes in the documents and edudoc folders? It's almost exclusively alignment fixes and changes from pure HTML to markdown/pandoc syntax in some of our old docs. My expectation is that you won't find any issues, as I tried being as thorough as possible, but it's good to have another set of eyes on the changes.

@thewca/software-team could you please review the changes in the root of the repo? Namely, the changes to the assets and bin folders, the README and my newly-created Dockerfile.

I will also review all of the aforementioned changes myself for good measure.

[dmint789]

@thewca/software-team also, I'll need someone to override the PR build test, cause it's failing due to not being up to date with these changes

[nsilvestri]

Thanks for seeing through this colossal effort. LGTM on behalf of WQAC.

[gregorbg]

This review includes the technical scripts only. I have not reviewed every single md file nor have I meticulously verified the generated PDF contents. That is left entirely up to WQAC.

[dmint789]

@gregorbg is this good to be merged now?

[dmint789]

Looks like all issues are resolved now

[gregorbg]

The technical build scripts have my approval. I did not (and will not) check the final rendered output of every single document in the new pipeline.

Sidenote: The CI error log looks like you forgot sudo somewhere

[dmint789]

Oh, maybe it's the apt commands. Also, does the build pipeline use the setup files from master or from this branch I'm trying to merge? I assumed the CI error would never go away until this PR is merged.

[dmint789]

@thewca/board can you please approve? This probably requires Board approval, because I had to edit many of the documents themselves, but the only real change is the last point in the description of this PR, but it doesn't even affect the rendered file, since the numbers themselves are ignored. I just wanted to fix the numbering in the Bylaws Markdown. I have personally checked the rendering of every single document in this repo, and everything has remained consistent, bar some very minor alignment here and there.

[dmint789]

@gregorbg Looks like I've answered my own question, as the PR build test has a different output after my commit now. I'll try to fix it, looks like the repos used by the github action are different from the ubuntu image repos.

[dmint789]

@gregorbg according to this, package version locking is not possible on ubuntu. I'd just remove the pandoc and weasyprint package versions and call it a day, unless you know of a way to get a specific version of these packages from apt.

[nsilvestri]

Approved on behalf as Board regarding non-content or formatting changes to Board-sensitive documents.

[dmint789]

@gregorbg the checks are finally passing. Can you please re-approve, cause the new commits made your approval stale. Maybe we can revisit package version locking in another issue and PR, cause this is currently blocking two of our projects.

pre-emptive