docs: migrate documentation to docusaurus + typedoc

[ephys]

Description Of Change

esdocs hasn't been updated in years. Causing issues such as the ones found in #13815

This PR migrates our documentation to Docusaurus. I picked Docusaurus in the hopes that this documentation platform is going to stay maintained, as it's developed by Facebook.

I also integrated TypeDoc to generate a smarter JSDoc that's capable of extracting data from typings annotations.

How this works

The documentation will not be placed inside the main repository anymore. It just doesn't work well with docusaurus's versioning system.

Instead, the documentation for v6 & v7 are moved to a new repository (ideally: https://github.com/sequelize/sequelize.org).
The old documentation websites for v3 to v5 are included as-is as static files. They are left completely unchanged (no url change):

the documentation for v6 & v7 are in docusaurus. v3 - v5 are left unchanged

That repository clones this repository, and generates the esdoc for v6, and typedoc for v7. Both are included as static files:

What this PR actually does

This PR:

• fixes a few jsdoc issues
• removes the documentation (moved to the new repo)
• replaces esdoc with typedoc

There will be another PR to the v6 branch to remove the documentation, as well as one in https://github.com/sequelize/sequelize.org

Some Screenshots

Click to expand!

Guides

TypeDoc

Pending question: How to handle website repositories

• resolved

Tagging @sdepold for this

We have 3 website repositories:

• https://github.com/ephys/new-sequelize-website (v6+, temporary repository)
• https://github.com/sequelize/sequelize.org/ (v3, v4, v5)
• https://github.com/sequelize/doc/tree/rtd (v1 or v2?)

I would propose doing a repository merge, with 3 branches, named:

• v6+ (docusauraus)
• v3-v5 (current sequelize.org repo)
• v1-v2 (current doc repo)

Pending question: How to handle old websites

• resolved

Tagging @sdepold for this

I can't reliably build the documentation for Sequelize v3 & v4 due to an incompatibility with python3.
https://github.com/sequelize/doc/tree/rtd is also old enough that it's difficult to build nowadays.

This is likely to get worse as years go by.

I propose building them manually one last time and committing their built files to a repository called 'website-build-archives' (or in a branch of the new website repo).

The new website will be able to include them as-is as static files, without having to build them.

PR Metadata

Resolved PRs

Closes #13769
Closes #11860
Closes #14104
Closes #13815
Closes #11856
Closes #10673

Todos

sequelize/website#10

[sdepold]

Will have a look tomorrow :)

[sdepold]

Seems that we are missing typedoc as a dev dependency?

edit: ah it's in the docs dir

[ephys]

My only gripe with this is that the TypeDoc integration in Docusaurus does not look remotely as good as what TypeDoc produces on its own.

I'd still go with Docusaurus, I value the "guides & tutorial" part much more than the JSDoc. But maybe we could generate the TypeDoc as a bunch of static HTML inside Docusaurus's static folder.

[sdepold]

I guess we would build the docs and upload the html files to the GitHub Pages branch?
yarn build seems to fail right now

[ephys]

It extracts the TypeDocs from the dist folder, did you build Sequelize itself first?

[sdepold]

Would you use this search feature? https://docusaurus.io/docs/search
I just ran yarn build in the root dir, and then yarn build in the documentation dir, and this is the result:

[ERROR] Docusaurus Node/SSR could not render static page with path /docs/api/ because of following error:
Error: Minified React error #62; visit https://reactjs.org/docs/error-decoder.html?invariant=62 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.

[sdepold]

Is the documentation directory the successor to the docs dir?

[sdepold]

I think I'm fine with docusaurus

[ephys]

Is the documentation directory the successor to the docs dir?

Can be, but I named it that way to avoid touching the docs dir until everything has been migrated. Either name works for me.

I'll have to look into the error. I also need to check if we can publish a fully static version.

Also yes to https://docusaurus.io/docs/search

[sdepold]

If we cannot publish a fully static side, we will have to change the build and deployment process. I think we could just deploy it to Heroku, if needed. Domain management will be a bit more challenging in that case however. Ideally we will be able to commit a bunch of html files into the website repo

[ephys]

Coming back to this: I think it's best if we generate two sites
The TypeDoc integration in docusaurus isn't great when compared to what base-TypeDoc generates: https://typedoc.org/example/
So docusaurus for manuals, typedoc for typedoc

[ephys]

Woops, looks like renaming a branch closes its associated PR.

[mmahalwy]

omg @ephys this is amazing.

[ephys]

The new website is very close to being ready, I think we can merge this PR and redirect all documentation changes PRs to the new repository.

[ephys]

Once this is merged, we'll need to add Lint code as a necessary check in the branch protection settings

[ephys]

This PR should only be merged once the website is just about to be released on the new domain, because it updates the different website urls in the readme (@sdepold)

[WikiRik]

@ephys there were several issues connected to this PR. Are they all resolved now? Since the scope of this PR did change throughout the months

[ephys]

Yes, most of them were about differences between the documentation in .d.ts files vs .js files

This one: #14104 isn't resolved in v6, but is resolved in v7.
I tried fixing it in v6 without success (see sequelize/website#43 (comment)) but as the issue was about v7, let's keep it closed and continue with sequelize/website#43 instead

[github-actions]

🎉 This PR is included in version 7.0.0-alpha.11 🎉

The release is available on:

• npm package (@release-v7 dist-tag)
• GitHub release

Your semantic-release bot 📦🚀