Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Publish rune docs to netlify #50

Merged
merged 1 commit into from
Dec 16, 2023

Conversation

Qkessler
Copy link
Contributor

Change Summary

As discussed on #48, we see valuable to publish the documentation to somewhere consumable, for future contributors to see the documentation without actually having the barrier of running cargo doc --workspace on their machines.

I tried different things and ended up choosing netlify. Netlify has a very powerful build system and it's running on Ubuntu, but it did not allow for apt-get installs. Since we need pango and gdk to run cargo doc on the crate, moved to Github actions.

As part of the same PR, I fixed all the warnings on cargo doc, making sure that the documentation is correctly published. The trick to deploy cargo doc is to deploy target/doc and then pair that with a redirect of the main page (configured rune-rs.netlify.app on my own account) to /rune which (as the main crate) has the info about the subcrates as well.

IMPORTANT: For this to work, you need to do the following steps. I would do the steps myself, but I imagined you would like to have control of the app itself, as the author of the project:

  1. Create a Netlify account if you don't have any.
  2. Create a new site with the Rune project on Github.
  3. Note down the site id.
  4. Change the site name to something like rune-rs, for https://rune-rs.netlify.app to work. I'll remove my site with the same name to avoid conflicts.
  5. Go to your profile, User Settings, Applications and Generate a No Expiry (or to be expired, although that will need changing the secrets whenever it expires again) Personal Access Token and note it down.
  6. Go to the SECRETS configuration of this repo.
  7. With the site id you noted down, add the NETLIFY_SITE_ID secret.
  8. With the personal access token you noted down, add the NETLIFY_AUTH_TOKEN secret.

The site will be published on any push to master, no need to publish on PRs!

Risks associated with this change

I don't really see a risk per se, other than needing to configure Netlify with the secrets of the Github repo.

Testing

Published the app on all my commits on the docs branch on my fork. Additionally, if you see the commit that is linked on this PR, the CI on that commit has the deployed app (running the CI I'm proposing as part of this PR).

I tried different things and ended up choosing netlify. Netlify has a
very powerful build system and it's running on Ubuntu, but it did not
allow for apt-get installs. Since we need pango and gdk to run `cargo
doc` on the crate, moved to Github actions.

As part of the same PR, I fixed all the warnings on cargo doc, making
sure that the documentation is correctly published. The trick to deploy
cargo doc is to deploy `target/doc` and then pair that with a redirect
of the main page (configured rune-rs.netlify.app on my own account) to
`/rune` which (as the main crate) has the info about the subcrates as well.

Closes CeleritasCelery#48
@Qkessler
Copy link
Contributor Author

Since I removed my own rune-rs site, you can already use that name on the steps above. If you are interested in checking how the documentation is published, I still published my site to https://qkessler-rune-rs.netlify.app. Enjoy!

@CeleritasCelery
Copy link
Owner

Thanks for working on this! I tried to follow your steps, but we will see how it actually goes.

@CeleritasCelery CeleritasCelery merged commit 4bf54d9 into CeleritasCelery:master Dec 16, 2023
13 checks passed
@CeleritasCelery
Copy link
Owner

Looks like it worked! https://rune-rs.netlify.app

I am wondering if we should change most of the pub(crate) items to just pub? It won't make a difference semantically because this is not a library, but it will make the docs look cleaner.

@Qkessler
Copy link
Contributor Author

Yeah, I did that on my core refactor as well.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants