Interim rendering

[mcfnord]

I don't like contributing when I don't really know the status of the current draft, so I try to run Jekyll locally. I've tried about three times and always end up in a big mess.

I wish Jekyll wasn't an apparent dependency for seeing the "latest" source rendered into a website.

I'd like to have a daily build to a known address that Google won't spider. Internally, Microsoft lets documentation authors view a rendering of a particular branch or PR on an intranet web server. Could we routinely render one or more branches/PRs to an unlisted web address?

[ignotus666]

It looks like there could be ways to do that (eg this or this), though it looks like only PRs made against the release branch could be previewed because it's what gh-pages uses to build the website from, which wouldn't be much use to us (most are against next-release). It also adds a fair amount of complexity (and maintenance).

Where are you getting stuck with Jekyll? Note that if you're on Windows, you won't be able to run the po4a script that generates the translated docs (it's Linux only for now) and the Jekyll build will always fail. You can however use the artifact created by each workflow run in the Actions tab, but a PR has to be made first.

[pljones]

You can however use the artifact created by each workflow run in the Actions tab, but a PR has to be made first.

It would be easier if the workflow could be run against a branch, though. Save raising the PR until you know it's worth it.

[ignotus666]

It would be easier if the workflow could be run against a branch, though. Save raising the PR until you know it's worth it.

With GH Actions enabled in your own repo, you can work on your branch, make a PR from it against e.g. next-release (your own fork of it), and the workflow will run and create an artifact. Create/delete PRs as you see fit (it's your repo), and none of it will show up here. Not exactly what you said, but close enough I think.

[mcfnord]

Where are you getting stuck with Jekyll?

I spin up a new instance of Ubuntu 22. I guess someone hinted about the PR making the artifacts and I tried that once. This is where I gave up this time:

So apparently I installed NodeJS after that, and got... farther?

I would like to see the next-release branch rendered regularly. Right now, for example, I think there's much changed in next-release that does not appear yet in the public site. So I wait until it goes live before offering full PR changes, which does kinda work for a while, and maybe that's enough.

Maybe a docker container could be made? I barely understand those, but think they can be pre-configured for easier installation.

[ignotus666]

Are you creating the translated files with the po4a script before running Jekyll? You need to install po4a (you can get it from the jamulussoftware/assets repo) and then run the po4a-create-all-targets.sh script in /_po4a-tools.

[mcfnord]

I did install this just now, but I think the failure has evolved into another error. cannot load webrick? LoadError?

Why is po4a a dependency for the English build of next-release branch?

What do you think about using docker to share this process? I'm still a docker beginner. I worry that there aren't many people who need a local build, but I am one such person. My workaround where I wait for a release and swarm the PRs really isn't too bad, but keeps me from trying some fixes.

[ignotus666]

The website is multilingual - there's no "English build", so all language files have to be generated for it to build properly.

Sorry, I know nothing about docker...

[ignotus666]

@mcfnord Well, turns out I can't get Jekyll to build the website locally either (same webrick (LoadError) message too)...

What's weird is if I download an artifact from the Actions tab, that will build ok. You could give that a go if you haven't already.

If it works, to get a build of next-release in its current state, make a branch of it in your repo, edit something trivial, and make a PR against next-release (make sure it's against your fork of it and that you've enabled GH actions). You'll get an artifact in your repo that'll be next-release plus whatever change you did to create the PR. Yeah, a bit convoluted, but not that hard either.

Oh, and no need to do anything with po4a - the language files will be there already.

[ann0see]

I think the error could be that the dependencies need to be updated (bundler update might fix it)

[ignotus666]

bundler update might fix it

That was it, thanks!

[ann0see]

Closing as completed - I think it is resolved by a local update. In future we'll need to update the live site too, but I think that still takes some time.