Closed daylinmorgan closed 2 months ago
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.
Well the docs don't need Python to build so don't claim that they do.
nim rst2html
(maybe it's calledmd2html
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.
I don't understand. Ping @ringabout, @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.
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)
@daylinmorgan, is https://gh.dayl.in/nimble/ built using this new process? I'd like to make sure everything works before we merge it.
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:
python
, mkdocs
, and mkdocs-material
.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.
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
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:
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.
Like this?
Edited:
Indeed, it works now => https://github.com/nim-lang/nimble/actions/runs/8748959902
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 setupmkdocs
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.