Add a user guide with examples #266
Conversation
|
There is a preview of what this looks like at: https://ehuss.github.io/cargo-bisect-rustc/introduction.html |
There was a problem hiding this comment.
Github has published starter workflows for publishing with Github Actions. I'd probably base this one on the mdBook workflow they've published instead of inventing my own.
Docs: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow
mDbook starter workflow: https://github.com/actions/starter-workflows/blob/main/pages/mdbook.yml
I also suspect that pinning the mdBook version will quickly result in outdated versions being used to build. Pretty sure Dependabot won't open PRs to update it.
One option would be cargo install mdbook but running that on each push is a waste of cpu cycles. Instead you could install it with taiki-e/install-action. That action gets regular updates so far, so I'd trust it more to stay up-to-date until proven otherwise.
Usage would be:
- uses: taiki-e/install-action@v2
with:
tool: mdbook
There was a problem hiding this comment.
I generally prefer to pin the version so that it uses a version known to work. Using something that installs an arbitrary "latest" version could break, particularly with semver-incompatible releases.
FYI, I'm the maintainer of mdbook. In terms of "inventing", this is the setup used on several rust-lang projects. There is a deploy script in simpleinfra which does something similar, but I prefer to keep it simple in terms of download, build, commit, push.
It might be nice to create a re-usable action hosted by rust-lang, but I haven't really had a chance to investigate what that would require.
There was a problem hiding this comment.
Using something that installs an arbitrary "latest" version could break, particularly with semver-incompatible releases.
Obviously. Unfortunately pinned versions end up being forgotten about and outdated all too often, which is why my preference would be putting out a minor fire once in a while if there's no better way to alert/remind me of updates that need to be done.
But since your preferences matter far more than mine in this repo: ¯\_(ツ)_/¯
|
@oli-obk Just checking if you had any thoughts on this? |
This replaces the old tutorial with a new book that goes into more detail on various topics. It also contains a suite of examples to show different uses.
Closes #264