Add Mdbook documentation

[YJDoc2]

This is the first draft for the Youki mdbook documentation. This is a WIP, and will be kept updating

This is temporarily deployed at https://yjdoc2.github.io/youki/index.html

[YJDoc2]

@utam0k @Furisto @yihuaf @tsturzl @tommady

Please take a look, suggestions and improvements are welcome!

This currently only covers the user-facing documentation, that is using youki as a low-level container runtime, or using sub-crate of youki workspace as a dependency.
I will keep updating this PR, adding the developer documentation.

Thanks :)

[codecov-commenter]

Codecov Report

Merging #560 (ecb8bb8) into main (1444578) will increase coverage by 0.04%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main     #560      +/-   ##
==========================================
+ Coverage   61.09%   61.13%   +0.04%     
==========================================
  Files          85       85              
  Lines       12563    12564       +1     
==========================================
+ Hits         7675     7681       +6     
+ Misses       4888     4883       -5     

[yihuaf]

LGTM on the first pass. Can you also document the deployment instructions? Should we generate the output to an individual repo, and serve the docs from there?

[utam0k]

That's great! If the mdbook is easily completed in this repository, that's preferable. It would be preferable to have the documentation updated with the feature change PR.
I'm concerned about what to do about the duplicate content in the README.

[YJDoc2]

The doc book will be contained in the docs/ , and can be easily updated with feature PRs, so that it stays updated with changes. After that we can also setup a CI action that will automatically deploy the updated book.

I copied the Readme from youki into the book, as I thought that would be good to make it self-contained, that way the book also indicates the intentions and thoughts behind youki. If you think there should be something else put there, I'll be happy to make that change 👍

@yihuaf I'll be adding the deployment of book section the the dev part of the book, as it seems to fit there better.

I'm working on the dev section of the book, and hopefully will be able to update it by today.

[utam0k]

💯

The doc book will be contained in the docs/ , and can be easily updated with feature PRs, so that it stays updated with changes. After that we can also setup a CI action that will automatically deploy the updated book.

How about making the tutorial a separate chapter?
I'd also like to add how to use it from the high-level runtime in the future.

I copied the Readme from youki into the book, as I thought that would be good to make it self-contained, that way the book also indicates the intentions and thoughts behind youki. If you think there should be something else put there, I'll be happy to make that change 👍

[yihuaf]

I'll be adding the deployment of book section the the dev part of the book, as it seems to fit there better.

Perfect :)

I'm concerned about what to do about the duplicate content in the README.

We can have a brief introduction to the project in README and link to the mdbook content. Then, the majority of the readme content can be moved to mdbook.

[YJDoc2]

Hey I have added the basic structure for the dev documentation. NOTE that this is NOT the final version, and I'll be going over the content once again, there are several TODOs and information to be added, but wanted to take you opinion on the topics/ chapters I'm planning to cover in the dev-documentation. Please take a look @utam0k @yihuaf

How about making the tutorial a separate chapter?
I'd also like to add how to use it from the high-level runtime in the future.

Currently the tutorial is a separate chapter (the basic setup and basic usage) , under the user-docuementation section, but if you wan it to be a top level chapter, that can be done as well. Let me know.

[YJDoc2]

Hey, I have updated the dev doc as well, and the only part remaining is the deployment instructions after we decide how to deploy this.

Currently we can deploy simply using GitHub pages, and for that we will need direct push access to this repo, so @utam0k you will probably have to do this manually. Later we can set up CI so that any changes to docs/ will trigger the deployment.

Please take a look @utam0k @yihuaf The updated changes are deployed at https://yjdoc2.github.io/youki/

Thanks :)

[utam0k]

Hey, I have updated the dev doc as well, and the only part remaining is the deployment instructions after we decide how to deploy this.

Currently we can deploy simply using GitHub pages, and for that we will need direct push access to this repo, so @utam0k you will probably have to do this manually. Later we can set up CI so that any changes to docs/ will trigger the deployment.

Please take a look @utam0k @yihuaf The updated changes are deployed at https://yjdoc2.github.io/youki/

Thanks :)

@YJDoc2
I registered secrets environment value to this repo.
Can you use secrets.ACTIONS_DEPLOY_KEY? If this fails, please let me know what permissions I need, because I may have set the permissions incorrectly.

[YJDoc2]

Hey, @utam0k , I checked out and we don't need any extra key, the default Key that GitHub itself provides to the actions will do. However if I understand it correctly, that would mean that whenever a commit is pushed to the main branch and has changes in the docs, it will deploy the book, even for the forked repo. I don't think it will be a problem, but if someone doesn't want to deploy, or has already set up a /youki path on their own github pages, this can potentially clash ( the chance of this happening seem very low, as that would only happen if someone has a different repo under name youki, which is not this one).

The push access I was talking about was for initial manual deployment of the docs, which will not be needed if we set up the CI, it was the way I used to deploy the book for may repo.

If you want I can add the CI script as well in this commit, let me know.

The example I am referring for the action is at https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-mdbook-rust

Edit :
Other than this, do you have any changes or requirements to be made in the PR?

[Furisto]

I do no have any specific comment, just wanted to say that this is pretty cool.

[YJDoc2]

I do no have any specific comment, just wanted to say that this is pretty cool.

Thanks you :)

@utam0k I have added a docs script as well which will run every time when commits pushed on the main branch and docs/ directory has changes, it will automatically update build the mdbook and deploy it on gh-pages branch, which should deploy the mdbook at https://containers.github.io/youki/ if I'm not too wrong

[utam0k]

I do no have any specific comment, just wanted to say that this is pretty cool.

Thanks you :)

@utam0k I have added a docs script as well which will run every time when commits pushed on the main branch and docs/ directory has changes, it will automatically update build the mdbook and deploy it on gh-pages branch, which should deploy the mdbook at https://containers.github.io/youki/ if I'm not too wrong

How about pushing it to the gh-pages branch?

[YJDoc2]

How about pushing it to the gh-pages branch?

?
Sorry I didn't understand . The build html files from mdbook will be pushed to the gh-pages branch by the action itself. As the gh-pages branch is the default that GitHub looks for, the action pushing the html files to that branch should automatically host the mdbook.

Please correct if I misunderstood.

[utam0k]

How about pushing it to the gh-pages branch?

? Sorry I didn't understand . The build html files from mdbook will be pushed to the gh-pages branch by the action itself. As the gh-pages branch is the default that GitHub looks for, the action pushing the html files to that branch should automatically host the mdbook.

Please correct if I misunderstood.

Oh I'm sorry. This is exactly what I was trying to say. It's not a problem.

[utam0k]

Awesome 🚀

[utam0k]

💯 🚀
https://containers.github.io/youki/