use GitHub Actions to deploy nimble guide.

[daylinmorgan]

This is a follow-up to #1190 to help facilitate this goal "IMO, the content itself can (and should) be improved once this is merged, so others can contribute."

Switching to instead use a Github Actions Deploy rather than the gh-pages branch for the documentation.

I also added a nimscript file at nimble-guide/config.nims to make it easier to setup mkdocs for hacking on the documentation.

Once merged the "Build and Deployment" source would have to be changed to "Github Actions" and the gh-pages branch can be deleted.

[Araq]

Well the docs don't need Python to build so don't claim that they do. nim rst2html (maybe it's called md2html these days) exists.

[daylinmorgan]

Well the docs don't need Python to build so don't claim that they do. nim rst2html (maybe it's called md2html these days) exists.

Maybe my wording was not specific enough but the documentation at nim-lang.github.io/nimble is generated using python + mkdocs (and mkdocs-material).
Certainly folks can generate html from markdown however they want but it won't replicate how the nimble-guide is actually currently built and served.

[Araq]

I don't understand. Ping @ringabout, @narimiran

[narimiran]

Well the docs don't need Python to build so don't claim that they do

Docs don't need it, but this new Nimble Guide does.

---

1. My question (for @daylinmorgan and anybody else) is: Is this really a simpler/better solution than the existing Makefile? (I'm fine either way, but would like to hear more opinions)

2. @daylinmorgan, is https://gh.dayl.in/nimble/ built using this new process? I'd like to make sure everything works before we merge it.

[daylinmorgan]

My question (for @daylinmorgan and anybody else) is: Is this really a simpler/better solution than the existing Makefile? (I'm fine either way, but would like to hear more opinions)

The main advantage of CI-based deployment is to remove some of the friction for updating docs. With the current strategy in order to deploy a new version of the docs two things must be true:

• You have to build locally which requires at a minimum: python, mkdocs, and mkdocs-material.
• You must have write access to push a new deployment.

By switching to using CI then anyone can submit documentation content changes in the form of a PR. Merging it into master would be sufficient to update the deployed docs, without requiring the follow-up step from a maintainer to rebuild and push the new docs!

If you are really wanting to keep a manual deployment to gh-pages, then I don't see the value proposition of a single-recipe Makefile over an easier to visually parse "deploy docs" script (in bash or nimscript), that wouldn't require backslashes and && operators. Realistically, though the simplest gh-pages deployment solution is already supported natively by mkdocs in the form of mkdocs gh-deploy.

FWIW the current deployment just adds the built docs at the root of the repo, unnecessarily maintaining the commit history of master and deploying files which are not documentation on the gh-pages branch.

---

@daylinmorgan, is https://gh.dayl.in/nimble/ built using this new process? I'd like to make sure everything works before we merge it.

That's correct! You can see the logs of the GitHub Action for the current deployment here.

It seems later this year the "deployment" step will be handled by the GHA infrastructure no matter what.

[ringabout]

Deployment failed due to

Branch "master" is not allowed to deploy to github-pages due to environment protection rules.

https://github.com/nim-lang/nimble/actions/runs/8748959902

Could we have an automatically built gh-pages instead? I used mkdocs gh-deploy before https://github.com/planety/prologue/blob/73c2cf3d8da11865907689d568aa472d78339500/prologue.nimble#L38C9-L38C25

[daylinmorgan]

Once merged the "Build and Deployment" source would have to be changed to "Github Actions" and the gh-pages branch can be deleted.

Was this changed that I said in the first comment made after PR was merged?

Additionally, since if the master branch is protected you would need to add it to the github pages environment following these steps:

1. Go to you repository Settings.
2. Click on Environments.
3. Select your environment github-pages.
4. Next to Deployment branches select Selected branches from the dropdown.
5. Click on Add deployment branch rule.
6. Enter the pattern "master".

[narimiran]

Was this changed that I said in the first comment made after PR was merged?

Yes.

Click on Environments.

I don't see that in the settings. It might be that I don't have a full access to this repo, so somebody else (with more priviledges) should follow the steps provided.

[ringabout]

Like this?

Edited:

Indeed, it works now => https://github.com/nim-lang/nimble/actions/runs/8748959902