new CI: build docs + preview

[pietroppeter]

the new CI should:

• build the docs
• add a preview like the one based on netlify used in scinim/getting-started

It would be nice also to document this type of CI, since I currently this looks like the best practice on nimib site deployment.

new CI would also mean removal of old CI which means removal of docs\ptest.nim (see #41). Testing would then be reduced to: check that docs do build (and maybe check that html files are generated).

Folder structure will need to change:

• all nim files currently in docs should be moved in a new folder docsrc (except for the above ptest)
• all html files currently in docs should be removed from git (and docs\*.html should be added to gitignore)
• nimib.toml should change srcDir to docsrc

In nimib we do not have (yet) a way to build a collection of documents (like we have in nimibook), we will have in the future a nimib executable for that purpose. For the moment a simple build task in nimib.nimble file could do the build. The logic would be to find all .nim files in srcDir and run nim r -d:release against them.

Other task that could be added to nimble file would be a check task that checks that expected html files were actually created and a clean task that removes all generated html files.

[pietroppeter]

@HugoGranstrom, to continue our conversation from #69, it would already be helpful just to have a general overview on how the netlify preview works:

• I see at least 2 pr in scinim/getting-started related to netlify preview (preview and tasks), but I guess also valid is involved (does preview depened on valid to be completed?). what is the purpose of each PR?
• what other setup do I need to do other than copying and pasting the CI files? set up a netlify account? set up some secrets on both github and netlify sides?

[HugoGranstrom]

The purpose of the 4 files:

• pr_tasks.yml: purely esthetical. It creates the "Task" saying that it's waiting for build at the very start. Without this, the Task first appears after the build is done.
• valid.yml: This is where the actual building and running of the files happen. It builds and then saves the produced files in an artifact which pr_preview.yml then loads and pushes to Netlify. You might have to tweak the paths of the commands if they differ in your case.
• docs.yml: This is your standard build CI. It is pretty self explanatory I hope.

The reason for this split between valid and pr_preview is that we don't want to run user-code (which have access to environment secrets) in an environment with access to our secret keys (secrets.NETLIFY_AUTH_TOKEN, secrets.NETLIFY_SITE_ID). So we first run the code in a safe environment and then save the produced files as an artifact. Then we run pr_preview which has access to the secrets and can load the artifact we just created and deploy it.

does preview depened on valid to be completed?

Yes exactly, it runs once valid has completed: link

what other setup do I need to do other than copying and pasting the CI files? set up a netlify account? set up some secrets on both github and netlify sides?

Yes you will need a Netlify account, and create a site there. You will need the secrets.NETLIFY_AUTH_TOKEN and secrets.NETLIFY_SITE_ID set in your repo. I don't remember every mouse click to get them but the plugin we use for deployment has some links for it: link to plugin. I don't think you need to add any tokens on the Netlify side though.

Important: Don't forget to turn off automatic deploys of PRs at Netlify. They automatically do all the stuff we do here, but limit you to 300 build minutes / month. And exceeding that limit might have some consequences (having to pay basically), so best to just turn them off even if you may not run a risk of exceeding it yet. We make us of Github's free CI instead and just use Netlify for deployment (100 GB / month bandwidth) 😎

Hope this answered most of your questions, if you have anymore or need clarifications, just ping me 😄

[pietroppeter]

It looks all I need to know for now, thanks!

[pietroppeter]

build docs completed in #89 (and #90, #91)

[pietroppeter]

And #92 adds Netlify preview and closes this issue