[RFC] regarding committing docs and auto-updating documentation website

[timotheecour]

I'm currently seeing docs/glob/regexer.html + other files

• committing docs doesn't seem good since these are autogenerated
  (see https://blog.kentcdodds.com/why-i-don-t-commit-generated-files-to-master-a4d76382564 for eg)

• https://citycide.github.io/glob/ should reflect latest docs (or at least have an option to show latest docs, eg via url, eg:

• https://citycide.github.io/glob/version/master/
• https://citycide.github.io/glob/version/0.8.0/

• ideally docs there would be updated after each PR merged, automatically

implementation

• I'm curious whether .travis.yml or .appveyor.yml be used for that purpose? (since these are run after each PR is updated I'm curious whether that use case is supported or how to do that simply)

• or maybe git hooks: https://www.digitalocean.com/community/tutorials/how-to-use-git-hooks-to-automate-development-and-deployment-tasks

• in github: webhooks https://developer.github.com/webhooks/creating/

[haltcase]

I've never generated artifacts like this using CI but it's a good idea (or hooks, if that's better). Would like to find a good way to do this.

[haltcase]

I started this but we're blocked by nim-lang/Nim#9155.

That issue is fixed in devel.

[timotheecour]

great! will try to follow up on nim-lang/Nim#9155.

[timotheecour]

btw, this would (obviously) be useful for all nimble projects out there so making this work would be awesome

[haltcase]

@timotheecour done! 🎉

Well, not done, but it works heh. There are definitely improvements to be made. Basically how it works is: untagged git commits do nothing extra on Travis and the tests are run as usual.

A tagged commit however (which should be a new version) will trigger a custom Travis deploy script found in .travis_deploy_docs. It builds the docs and overwrites the master directory on the gh-pages branch, then also creates a new directory named with the tag on the commit.

Now I want to put in an index file that catalogs these versions and I think we'll be in good shape.

[timotheecour]

Now I want to put in an index file that catalogs these versions and I think we'll be in good shape.

after that I think it'd be worth adding a link to that technique to nim github repo in best practices (permanent, easy to search) or at least a forum entry so others are encouraged to do the same

EDIT
looks like for nim repo itself there's something along those lines since 15 days ago:

"Deploy devel build of docs to https://nim-lang.github.io/Nim" since nim-lang/Nim@308710c

links

• Visit https://nim-lang.github.io/Nim/ for the latest docs built from the Nim devel branch.
• https://github.com/kaushalmodi/nim-nightly-docs
• http://devdocs.io/nim/
• https://nim-lang.github.io/Nim/ => Made with Nim. Generated: 2018-10-03 04:41:01 UTC

[haltcase]

Aight, now it's pretty great. Check it out: https://citycide.github.io/glob/

• added a landing page with quick links to the GitHub repo and latest docs
• added previous releases all the way back to v0.1.0
• added release history with links to docs & release notes for that version
• added some redirecting index files so {url}/{tag} is equiv. to {url}/{tag}/glob.html
  (eg. https://citycide.github.io/glob/v0.9.0 redirects to https://citycide.github.io/glob/v0.9.0/glob.html)

[timotheecour]

perfect!