feat: setup documentation website & document codebase with typedoc comments

[pedroalves0]

🗺 Overview

With the migration from the REST API to the Sync API we've decided to split the SDK documentation from the API website (https://developer.todoist.com/).

The documentation tool we settled on is typedoc and the content is published by a Docusaurus-generated website. To bridge typedoc with Docusarus the typedoc-plugin-markdown is used together with docusaurus-plugin-typedoc.

A separate PR will follow to automate the deployment of the Docusaurus website to GitHub pages.

Note: Although this PR is quite big, many files were generated by Docusaurus and do not need to be reviewed. For instance, all the *.md files besides about.md and authorization.md are auto-generated from typedoc comments.

Note: You'll see references to https://developer.todoist.com which don't quite match the SDK methods input and output. This is expected for the moment, as the API v9.208 is only documented internally.

🔗 Reference

• feat: [BREAKING] migrate from REST API to Sync API #263

🧪 Test plan

• Changes introduced here have been manually tested by someone other than the PR author.

• cd to todoist-api-typescript/website

• Run npm run start

• Check out the documentation website served at http://localhost:3001/

[rfgamaral]

I had to run npm install both in the project root and the website folder, but in the end I got it working. I wonder if it wouldn't make sense to "convert" this project into a monorepo, one package for the source, another for the website. It would probably make maintenance and development a bit easier. Something to consider, if you have the time.

Also, the port is :3000, not :3001 as described in the test plan (but it doesn't matter because the port is printed in the terminal and the browser auto starts with the correct port).

That said, the website looks good, and now that I know that we are using Docusaurus for this, I can see that many documentations I've looked into in the past also used Docusaurus, so I guess we did the right choice going with this tool.

[pedroalves0]

I wonder if it wouldn't make sense to "convert" this project into a monorepo, one package for the source, another for the website. It would probably make maintenance and development a bit easier. Something to consider, if you have the time.

While I can see the benefits of converting to a monorepo, the uncertainty around auto-generated SDKs makes me not want to introduce any more drastic changes. Additionally, when implementing this PR changes, I looked into how other repos structure their Docusaurus website and having a website folder is a common pattern.

[rfgamaral]

I looked into how other repos structure their Docusaurus website and having a website folder is a common pattern.

I don't doubt that, but I picked one at random, and it uses a monorepo: Ionic 😅

While I can see the benefits of converting to a monorepo, the uncertainty around auto-generated SDKs makes me not want to introduce any more drastic changes.

That makes sense 👍