Add mdbook and GitHub pages deployment #319
Conversation
This comment has been minimized.
This comment has been minimized.
|
Can we merge this after release? Otherwise we have to review all our docs all over again, make sure our quickstarts still work etc. It's just a big sweeping change when we have limited time. |
|
Another question on this format - if changes from If I'm an end user is there an easy way for me to just see documentation for the release version? |
There was a problem hiding this comment.
This will also need to change the documentation links on https://github.com/googleforgames/quilkin/blob/main/README.md, as if we merge this, then they all break.
|
Another thought - can we add what you need to install etc to run this locally to our development guide? If we want to go super above and beyond a |
|
Just checking gh-pages enablement. If you want to do a preview, I need there to be an existing branch. I had a quick peek, and there doesn't seem to be a gh-pages branch yet. Drop me a note when it's there, and I'll turn things on 👍🏻 (Maybe do it manually to get started?)
On review, I'm less concerned with this PR before release - just want to make sure that none of our links to documentation break. |
There was a problem hiding this comment.
Just digging into mdbook a bunch, and I have lots of questions 😄 - it's super cool though! I especially love the idea of being able include rust files directly, since we can tie that to CI. Excellent suggestion to move us to mdbook!
- Does this also build the rust API docs and push them to github pages, or just the pages in
docs/src? (I don't think it does the rust api docs, but wanted to be sure). If not, should we? - I'd love to see this also include the work to integrate
mdbook testinto CI, so that we know everything passes on each PR run (unless you are going to do this in a follow up PR? -- we should probably ticket this work then). - Related to above, re: overwriting github pages with each post to
main-- can we make snapshots for each release? It would be nice ifmainpoints to something like/developand each release is a/0.1.0/, and/0.2.0/directory etc. Since the API is likely to change a bunch, I expect it will be useful for people to be able to go back in time and see how the documentation changes / or check the documentation for the release they are currently using.
Not sure if it 100% solves the initial broken docs on merge issues, but one other thought I had was to point the documentation links in the README.md to the release branch for the time being, until we feel very confident in this new platform, and we can then make a switch over. Just an idea though.
I forgot that's how that works, then you'll just need to enable it after this has merged then. The branch will be created on the first successful run.
This does also build the Rust API docs and publishes them under
I can add those. |
XAMPPRocky
force-pushed
the
deploy-docs
branch
3 times, most recently
from
a1e4312 to
4651ca6
Compare
|
Added snapshotting. So now this runs when we've pushed or tagged a release with |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
1 similar comment
This comment has been minimized.
This comment has been minimized.
|
Build Succeeded 🥳 Build Id: 9bb613f9-1d0f-451e-98a5-12c199c59feb To build this version: |
|
Once we are done with release, I'm going to try and run this on a personal fork (I believe we can do that with github actions?) so we can have a live previous of what this looks like and triple check everything is working as expected. This is going to be nice though - I can see how this is going to setup lots of nice improvements in the documentation. 😄 |
|
Ran it again, ran into a stack of issues unfortunately. Have fixed several things here: (Ignore where I have
Successful run: I learnt some things about github actions though! Preview: I haven't had a chance to review the docs yet, but at least we can now see them 🙌🏻 I also haven't tested it against creating a tag, so one of us should also take that for a spin so we can make sure it works as expected. That will likely be my next step unless you get to it first. |
|
Tagging seems to be working as expected (as long as the action are in the tagged content). I cleaned up the GH pages on my fork, and manually made a snapshot for 0.1.0 - once we resolve the below blocking issues, and if we're happy, I'll push it to main Quilkin repo, and make a PR to point the README.md to it, and then we can get this merged with my fixes. (TIL you can't make a PR to a branch that doesn't exist!) 0.1.0 documentation (guide, api) The blocking issues I found were:
I am keen to get this merged before we change the API surface, as otherwise it becomes quite difficult to get a mdbook snapshot of 0.1.0 (which we are still inline with at this point). The other option is: We skip a snapshot of 0.1.0, and instead point the documentaton for 0.1.0 straight at https://github.com/googleforgames/quilkin/blob/release-0.1.0/README.md, and then 0.2.0 will be the first documentation snapshot we take with mdbook. Thoughts? |
Break out a section on the README.md linking to tagged snapshots of documentation, so that as API changes occur it's still easy to see previous API documentation and accompanying guides. It also stops new users from getting confused by in-flight API changes. I believe this will aso unblock googleforgames#293 and also remove the requirement to get a 0.1.0 snapshot for googleforgames#319, which could block other PRs as well.
Break out a section on the README.md linking to tagged snapshots of documentation, so that as API changes occur it's still easy to see previous API documentation and accompanying guides. It also stops new users from getting confused by in-flight API changes. I believe this will aso unblock googleforgames#293 and also remove the requirement to get a 0.1.0 snapshot for googleforgames#319, which could block other PRs as well.
Break out a section on the README.md linking to tagged snapshots of documentation, so that as API changes occur it's still easy to see previous API documentation and accompanying guides. It also stops new users from getting confused by in-flight API changes. I believe this will aso unblock googleforgames#293 and also remove the requirement to get a 0.1.0 snapshot for googleforgames#319, which could block other PRs as well.
Break out a section on the README.md linking to tagged snapshots of documentation, so that as API changes occur it's still easy to see previous API documentation and accompanying guides. It also stops new users from getting confused by in-flight API changes. I believe this will aso unblock googleforgames#293 and also remove the requirement to get a 0.1.0 snapshot for googleforgames#319, which could block other PRs as well.
|
Build Succeeded 🥳 Build Id: 046bb167-2429-40f3-8883-c69cad97ac72 To build this version: |
XAMPPRocky
force-pushed
the
deploy-docs
branch
2 times, most recently
from
3b84fd6 to
0345602
Compare
|
Build Failed 😭 Build Id: e1ff381d-4a8f-4c97-be62-eb6c1d20c0c1 Status: FAILURE To get permission to view the Cloud Build view, join the quilkin-discuss Google Group. |
|
Build Failed 😭 Build Id: fa8327bd-fdc4-48f6-a85c-505e449494fc Status: FAILURE To get permission to view the Cloud Build view, join the quilkin-discuss Google Group. |
Well you can't link to it directly in the TOC, and we already link to that page in the introduction, so if we want a more detailed page, I think that should come as a separate PR. I've implemented the rest of the feedback. |
|
Build Succeeded 🥳 Build Id: 8f0ff355-4667-4f09-94f9-8d08afb83a1c To build this version: |
There was a problem hiding this comment.
Let's add an examples page that points to https://github.com/googleforgames/quilkin/blob/main/examples (I'd love to have it point to the same release branch as the snapshot with something like mdbook-variables, but can experiment with that later, I'm sure an explanatory note that they might need to switch to the correct release tag will in the repo will suffice).
Well you can't link to it directly in the TOC, and we already link to that page in the introduction, so if we want a more detailed page, I think that should come as a separate PR.
Sounds good, I'll jump on it once this has merged 👍🏻
(Reminder to myself: Update the release guide once this has merged too, to link to the tagged snapshot from README.md)
|
Build Succeeded 🥳 Build Id: 8a19e188-70a0-4b8d-99b3-d8091d75c5ec To build this version: |
|
Build Succeeded 🥳 Build Id: bb76fe42-95ab-47bb-a6d3-e4c0ffd1b86e To build this version: |
Co-authored-by: Mark Mandel <[email protected]>
markmandel
force-pushed
the
deploy-docs
branch
from
40bdc9b to
bb3464a
Compare
|
Build Succeeded 🥳 Build Id: 3a75105e-b8b4-4f20-bf8a-0d919f324986 To build this version: |
This PR adds mdbook for documentation and adds a GitHub Action to deploy both it and the API documentation to GitHub pages, so we'll always have the latest documentation available if needed.
@markmandel You'll need to enable GitHub Pages in settings for this to work.