Migrate docs to docusaurus

[srdtrk]

Description

This PR:

• Migrates the docs to docusaurus.
• Uses the docs theme from cosmos-sdk.
• Allows navigation to ADRs from the navbar.

closes: #3492, #3002

addresses: #3488

Structural Changes

Markdown Files

In the previous VuePress layout, markdown files could be placed anywhere within the docs project directory. The organization of the monolithic sidebar was managed by adding new entries to the sidebar in docs/.vuepress/config.js.

The new layout introduces multiple sidebars separated by the navbar. Currently, there are two sidebars: Documentation and Architecture Decision Records (previously, ADRs were not accessible through the website). To add new entries to the navbar, you edit the docs/docusaurus.config.js file. These two sidebars are autogenerated from the content found in the docs/docs/ directory (for the Documentation sidebar) and docs/architecture/ directory (for the ADRs sidebar).

In the previous layout, documentation markdown files (those displayed on the website) were distributed across several directories:

docs/
├── README.md
├── apps/
├── architecture/
├── assets/
├── client/
├── ibc/
├── middleware/
└── roadmap/
...

In the new layout, all markdown files displayed under the Documentation tab (in the navbar) are located within the following directories (including subdirectories):

docs/docs/
├── 00-intro.md
├── 01-ibc/
├── 02-apps/
├── 03-ibc/
├── 04-middleware/
└── 05-migrations/

The naming conventions for these files are explained in docs/README.md. ADRs still reside in the docs/architecture/ directory, as in the previous layout. Docusaurus can still autogenerate the navbar page correctly for ADRs, with the only change being the modification of docs/architecture/README.md to ensure Docusaurus places it at the top of the autogenerated ADR sidebar.

There are three other unchanged directories besides docs/architecture/:

docs/
├── dev/
├── events/
└── requirements/
...

These folders contain markdown files that are not accessible from the website for various reasons:

• dev/ includes guides for creating PRs, issues, and etc.
• requirements/ contains the requirements for specific IBC features.
• events/ includes a deprecated markdown file about events emitted by ibc-go modules.

Images and Other Static Files

Previously, all images, including those used in documentation markdown files, were treated as static files and stored in the docs/assets/ directory. This was one of the reasons why docs versioning had to be managed through GitHub tags/releases.

The new layout differentiates between images used in documentation files (such as those in docs/docs/ markdown files) and truly static images (like website icons, banners, and logos). Static images are stored in the docs/static/img/ directory, while images used in documentation markdown files are kept in the ./images/ directory within the same directory as the markdown files. This means that each category has its own ./images/ directory, as seen in docs/docs/:

docs/docs/
├── 01-ibc
│   │ ...
│   │
│   ├── 04-middleware
│   │   ├── 01-overview.md
│   │   ├── 02-develop.md
│   │   ├── 03-integration.md
│   │   ├── _category_.json
│   │   └── images/
│   │ ...
├── 02-apps
│   ├── 01-interchain-accounts
│   │   │ ...
│   │   │
│   │   └── images/
│   ├── 02-transfer
...

Commit Message / Changelog Entry

docs: migrate to docusaurus

see the guidelines for commit messages. (view raw markdown for examples)

---

Before we can merge this PR, please make sure that all the following items have been
checked off. If any of the checklist items are not applicable, please leave them but
write a little note why.

• Targeted PR against correct branch (see CONTRIBUTING.md).
• Linked to Github issue with discussion and accepted design OR link to spec that describes this work.
• Code follows the module structure standards and Go style guide.
• Wrote unit and integration tests.
• Updated relevant documentation (docs/) or specification (x/<module>/spec/).
• Added relevant godoc comments.
• Provide a commit message to be used for the changelog entry in the PR description for review.
• Re-reviewed Files changed in the Github PR explorer.
• Review Codecov Report in the comment section below once CI passes.

[damiannolan]

Awesome work getting this effort started! Much appreciated ❤️

The diff is quite large and seems like its showing some unrelated files. Is it possible for me to build and run the docs locally? That way I'd be happy to leave my approval by sanity checking a local deployment.

This PR doesn't change any of the contents, correct? It is just the structural changes to allow rendering the new markup?

[DimitrisJim]

@damiannolan yeah, just npm install followed by npm start in the docs/ folder to fire it up locally. The steps are somewhere in the PR but difficult to find due to the # of changes.

[DimitrisJim]

running this locally seems perfectly fine to me and looks dope 🥳 left a couple of questions/comments.

[DimitrisJim]

dunno if this is necessary but seems kinda difficult to find this? I.e wouldn't know to look into docs/01-ibc for this, would expect it to be more top level like previously.

[DimitrisJim]

can't seem to find where this was moved. It might have been deleted alltogether since it was just pointing to another location?

[damiannolan]

ACK general structural layout. Local render looks great.

As a side note for a follow up PR it may be nice to add a main page under "IBC Application Modules" with a table of contents linking to transfer and interchain-accounts docs as well as a short blurb and link to the cosmos/ibc-apps repository.

[colin-axner]

Followup ACK. Thanks again for the work @srdtrk! I left some followup comments/questions, but I'm happy to see them addressed in followup pr's to the feature branch