Build docs with VitePress for v4

[javierjulio]

This is a work in progress to prepare for v4 beta release. This removes sections from the documentation that no longer apply on v4. We'll use VitePress for a new documentation site on GitHub Pages.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 99.10%. Comparing base (59a8627) to head (04fa22f).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #8194   +/-   ##
=======================================
  Coverage   99.10%   99.10%           
=======================================
  Files         140      140           
  Lines        4029     4029           
=======================================
  Hits         3993     3993           
  Misses         36       36           

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[mgrunberg]

@javierjulio have you considered keeping the content of current docs (v3)? This has two pros:

1. Users will be able to access old versions doc. Something good until they manage to upgrade to latest version.
2. We can merge this PR and keep evolving v4 docs on other PRs. Now we have to merge stuff to master and rebase this PR to make changes.

Just to be clear, I'm talking about the content, not the styles/UI (we should use VitePress now on for any version doc).

I can work on this idea if it makes sense.

[javierjulio]

@mgrunberg yes but only with a repository link to the docs folder on the 3-0-stable branch. Vitepress doesn't support documentation versioning. We could probably move the v3 docs into a subfolder and then use the multiple sidebars feature which is path based alongside a nav option to select the current or v3 docs.

[javierjulio]

@mgrunberg I extracted the general updates that were version independent #8424 and merged that in. Let me know if you are still interested in trying something out for docs versioning or to first share an approach to see if it's something we'll consider. Thanks!

[mgrunberg]

@mgrunberg I extracted the general updates that were version independent #8424 and merged that in. Let me know if you are still interested in trying something out for docs versioning or to first share an approach to see if it's something we'll consider. Thanks!

I'm still interested in this. I'm still figuring out how to do this but here is what I have in mind.

use the multiple sidebars feature which is path based alongside a nav option to select the current or v3 docs.

I want to achieve something like that.

What I have in mind is:

1. Keep v3 doc in 3-0-stable branch
2. Fetch docs during doc-build process

Why fetching during build? I don't want to carry over old doc files in master. If old docs need an update (backport of a feature?), it make more sense to do the PR in that version branch. I understand that we still gonna need to trigger a workflow in master to deploy the docs. It's a downside but nothing too bad in my opinion.

I haven't thought a lot on how to fetch. Could be a node fetch, a git export, a git submodule. There are ways for sure.

Following this idea, I'm wondering if the first step should be migrate current doc (v3) to vite-press. I don't know if there is a blocker for that.

Anyway, that's on my head. What do you think.

Oh, before I forget. I won't be able to work on this until Friday.

[javierjulio]

I think that may be too much or too problematic since the v3 docs have to map to the expected pages which would change in the new setup. I don't mind duplicating the v3 docs on master branch since we need to build a single site and deploy it. I believe it would be easier to include the v3 docs in the new Vitepress setup. We'd have to do some formatting updates (e.g. fix headings) in some cases anyway. You are welcome to try either approach but figure just easiest to work with duplicate v3 docs in master. No rush on this. Thanks for expressing an interest in tackling it!