search

rook / rook.github.io

Apache License 2.0
25 stars 30 forks source link

docs: use mkdocs and restructure docs #130

Closed galexrt closed 2 years ago

galexrt commented 2 years ago

Use rsync for syncing jekyll build changes to gh-pages branch

Signed-off-by: Alexander Trost galexrt@googlemail.com

This removes the existing docs/ dir and all its contents as they are not needed like this anymore. The rendered version is in the gh-pages branch (separate PR to update that branch as needed).

DO NOT MERGE!

galexrt commented 2 years ago

We need a way to order the topics. For example, it is really confusing that Getting Started is so far down the list.

I'll look into that the next days, to note this is something that is addressed at each project and not here (anymore).

The docs from master are called "latest" in the current docs instead of "master" in the link and url

I switched the master branch docs to master as I think most users probably assume latest is the latest release (/stable) version. I can change it though it would prefer to keep it at that, as the latest (alias) right now will always point to the latest release tag.

The style of the version dropdown looks awkward

I have to see if I can change something and / or get in contact with the theme developer.

I see the v1.8 and older docs all have the old style. How about we keep the older style for v1.9 as well, and just develop on the new style in master? Then when everything is finalized and looks good for the master docs, we can consider backporting to v1.9 as well.

For testing purposes I have switched the v1.9 to the "new" design, will revert that tomorrow in the gh-pages branch.

What if we have both tabs and the directory on the left column? The tabs may not be obvious to new-comers, so they might miss content.

I have to check if having both is possible. I have found some info on how I might be able to order the navigation and sections better.

travisn commented 2 years ago

The docs from master are called "latest" in the current docs instead of "master" in the link and url

I switched the master branch docs to master as I think most users probably assume latest is the latest release (/stable) version. I can change it though it would prefer to keep it at that, as the latest (alias) right now will always point to the latest release tag.

The current approach was following the pattern of Ceph latest docs. The latest docs have a message at the top that it is just a development version. I'd suggest we stay with that approach unless there is a need to change.

galexrt commented 2 years ago

I have found a way to organize the sort order of pages and sections. Will work on reordering the pages and update the demo.

galexrt commented 2 years ago

@travisn Yes, they are still there they are currently on the https://github.com/koor-tech/rook.github.io/tree/gh-pages branch and that branch once created might cause issues so I want to create it once we are ready to do the "switch".