Add, improve, rewrite and automatically render and deploy documentation #551
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This does the basic Docusaurus setup and moves all our existing docs roughly in the correct place. Most of the documentation was not adjusted yet to better fit this new form of presenting it. This is only the first step.
This also adds quite a bit of documentation, e.g. the auth example of using your own login page and session management. I deliberately included two documents that only have a "TODO" in them.
We use double quotes everywhere.
Then it looks cleaner and people are not frightened away by "so much to read".
LukasKalbertodt
force-pushed
the
docusaurus-docs
branch
from
73b3698
to
30b1041
Compare
|
🚀 This PR was deployed at https://pr551.tobira.opencast.org. The deployment will be updated whenever someone pushes onto this PR's branch. |
JulianKniephoff
added
changelog:admin
LukasKalbertodt
force-pushed
the
docusaurus-docs
branch
from
09cdc1c
to
a137897
Compare
LukasKalbertodt
force-pushed
the
docusaurus-docs
branch
from
a137897
to
1513d27
Compare
JulianKniephoff
requested changes
Sep 15, 2022
LukasKalbertodt
force-pushed
the
docusaurus-docs
branch
2 times, most recently
from
8554e45
to
80c9813
Compare
LukasKalbertodt
force-pushed
the
docusaurus-docs
branch
from
80c9813
to
3e33682
Compare
JulianKniephoff
approved these changes
Sep 15, 2022
Merged
LukasKalbertodt
added a commit
that referenced
this pull request
Oct 4, 2022
Some follow up improvements to #551.
Merged
JulianKniephoff
added a commit
that referenced
this pull request
Nov 29, 2022
As already mentioned in #551, we wanted to set up versioned docs, allowing users to switch to docs of a different version. We decided against storing old docs on our main branch. So instead, we automatically retrieve the old docs from git history. The main part of this PR is the script that does exactly that and sets everything up as expected by docusaurus. The CI makes use of that and deploys the versioned docs.  The latest released version is the default docs that are shown to people. Everything on `master` is shown as "Next". Docusaurus has some hints on how to properly do versioned docs. Most importantly "don't have too many versions". Luckily, `versions.txt` lets us easily select what versions we want (that's the reason for the manual file). I would think that for each major version, we only keep the latest minor one. Except for the latest major version where we keep all minor ones? We will see.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I wanted to do that for a while already. This PR renders our documentation with Docusaurus. For that, I had to rewrite lots of it and bring it into a slightly different structure. I also added a few pages of documentation. Finally, it is automatically deployed via GitHub pages from the master branch.
I think it's a really nice improvement and reading the docs in this new format feels a lot better.
Future improvement
Potentially still in this PR, but not necessary (i.e. feel free to merge before):
After this PR, or more precisely once we release a new release:
Docusaurus supports versioned docs, showing a version selector in the header. This is super useful. But since until now, our docs were not in a state where we can render them with Docusaurus, it's not possible to add previous versions, i.e. we would only have one version. So we need to wait to actually have multiple versions.
But for the record, we already talked about how we would do it. And in short: the documentation build action would basically check out a list of tags (previous releases) and copy their docs into
versioned_docs. We don't want to keep all doc versions on our main branch.