feat(docs): migrate docs to docusaurus #4693

srdtrk · 2023-09-18T11:41:48Z

Description

Warning: Do not update this branch as it is merge sensitive. I will do merges manually

Part of #3488. This PR:

Migrates docs to docusaurus
Manages versioned docs in main
Adds a search bar to the website
Displays ADRs in the website
Adds a new markdown linter

To view the docs, run

make build-docs && make serve-docs

Commit Message / Changelog Entry

feat(docs): migrate docs 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.

The following stack was used: - Docusaurus 2 - tailwindcss - postcss Min required node version is: 16.14 --------- Co-authored-by: colin axnér <[email protected]>

…saurus

…usaurus

# Conflicts: # CHANGELOG.md # docs/.vuepress/config.js # docs/docs/01-ibc/09-roadmap.md # docs/docs/05-migrations/10-v7-to-v8.md # docs/versions

* docs: added version 7.0.0 docs, need to check for bugs * docs: renamed the version to v7.0.0 * docs: added v6.1.0 * docs: added v5.3.0 * docs: added v4.4.0 * docs: updated the base url redirect, and version banners * docs: replaced 'Pre-requisites Readings' -> 'Pre-requisite readings' * docs: added missing ADRs to README.md * docs: added versioning info to README.md * docs: replaced '../../../../docs/architecture/adr-001-coin-source-tracing.md' -> '../../../architecture/adr-001-coin-source-tracing.md' * docs: updated the url of the 7.0.0 (latest) * docs: fixed all broken links * docs: updated 'make build-docs' command to use docusaurus * docs: Added a Links section to README.md * docs: updated code blocks in 02-integration.md to use docusaurus features as an example * docs: removed all TODOs from README.md * docs: updated the typical versioned docs tree in README.md * docs: made file naming section more precise * docs: updated README.md * docs: updated release-tracker.md * docs: removed search section from README.md * docs: updated release-management.md * docs: updated Makefile * docs: fixed more broken links * docs: updated workflows to only run when changes to main occur (not releases) * fix(ci): attempt to convert absolute urls to absolute filepaths in the ci * fix(ci): added '@site/' to ignorePatterns instead * imp(docs): removed wrong comment * fix(ci): fix markdown-link-check for docusaurus * docs: changed architecture links to absolute links * fix(ci): replace only affects architect and event links now * docs: fix broken more links * imp(ci): ignore http links in markdown-link-check replace statements * imp(ci): markdown-link-check should only run on modified md files * fix(ci): attempt to fix markdown-link-check * fix(ci): only check modified files for markdown-link-check * revert(ci): reverted link-check.yml to initial state * imp(ci): set link check timeout to 16 mins * imp(ci/link-check): link-check should ignore versioned_docs now * fix(ci/link-check): attempt to ignore files ending with '/' * docs: fixed broken link * docs: fixed broken link in RELEASES.md * fix(ci/link-check): config works now * refactor(ci/link-check): combined two regexp patterns into one in link-check config * fix(ci/link-check): config is good - attempt to fix the workflow * fix(ci/link-check): config is good - attempt to fix the workflow * fix(ci/link-check): added verbose mode * revert(ci/link-check): reverted workflow to initial state (not config) * nit: broke a link to test ci * revert(docs): fixed broken link * build(docs/deps): updated docusaurus to 2.4.1 * docs: replaced intro titles * docs: remove extra ')' * docs: wrapped some prerequisites in note * docs: replaces '::: tip' with ':::tip' * docs: replace '::: warning' with ':::warning' * docs: fix styling error * docs: readme updated * docs: removed all references to 'order:' frontmatter * docs: fixed list styling in transfer/state-transitions * docs: removed unneeded quotation * imp(docs): improved the markdownlint settings * imp(docs): improved the markdownlint settings * docs: ran markdownlint with the new config * docs: do not lint autogenerated CHANGELOG.md * docs: removed 'bash' from the codeblock in the PR template * docs: added '.github' to .markdownlintignore * imp(docs): added more comments to markdownlint config * docs: fixed incorrect category linking * docs: fixed indentation issue in fee middleware * imp(docs): added two more rules to markdownlint * docs: ran 'make docs-lint' * docs: made transfer the first app * docs: made transfer the first app in all versions * imp(makefile/docs): added link-check to makefile * docs: added back the spaces * docs: fixed a lint violation * docs: contents of DOCS_GUIDELINES.md have been merged with README.md * docs: ran markdownlint-cli * docs: fixed a lot of linting errors * docs: fixed a more linting errors * docs: fixed all linting errors * docs: corrected PR template's code box * imp(docs): add a new workflow for linting changed markdown files * docs: fixed linter violation * imp(docs): switch to using markdownlint-cli2 * revert(ci/markdown-lint): original state * imp(ci/markdown-lint): fix an error * imp(ci/markdown-lint): only runs on PRs which modify .md files * imp(ci/markdown-lint): only runs on PRs which modify .md files not in .github * docs: fixed broken link * imp(ci/link-check): this workflow only runs if a .md file has been modified * deps(docs): ran 'npm i --save @easyops-cn/docusaurus-search-local' * feat(docs): added local search bar * fix(docs): search bar highlight color is not buggy anymore * imp(docs): added term highlighting to search * fix: merge conflicts * docs: ran linter * refactor: removed markdownlint changes in this PR * refactor: removed markdownlint changes in this PR * refactor: removed linkcheck changes in this PR * revert: changes in PR template * revert: added swagger-docs thing back * revert: "revert: added swagger-docs thing back" This reverts commit f6cdcdb. * revert: "revert: changes in PR template" This reverts commit 5a23809. * revert: "refactor: removed linkcheck changes in this PR" This reverts commit b401b31. * revert: "refactor: removed markdownlint changes in this PR" This reverts commit eb31283. * revert: "refactor: removed markdownlint changes in this PR" This reverts commit d5b74e0. * add extra path to ignore * docs linting * Update docs/docs/01-ibc/09-roadmap.md Co-authored-by: Charly <[email protected]> --------- Co-authored-by: Carlos Rodriguez <[email protected]> Co-authored-by: Charly <[email protected]>

* ci: switched to docusaurus check and deploy workflows * ci: added workflow_dispatch back to deploy-docs

colin-axner

utACK, I mostly just verified that only the files expected to be modified are modified

scripts/linting/lint-changed-md-files.sh

charleenfei

thank you @srdtrk, just two small comments!

charleenfei · 2023-09-19T09:51:35Z

CODE_OF_CONDUCT.md

@@ -34,7 +34,7 @@ This Code of Conduct applies both within project spaces and in public spaces whe

 ## Enforcement

-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at <[email protected]>. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.


just making sure we own this address, right?

also, another bigger topic, but probably there needs to be more explicit steps here. but just flagging it for a larger discussion 🤗

CONTRIBUTING.md

damiannolan · 2023-09-19T10:11:07Z

What version of node is required to run this locally? (currently on v14.15.0)

file:///Users/damiannolan/development/ibc-go/docs/node_modules/@docusaurus/core/bin/docusaurus.mjs:30
process.env.BABEL_ENV ??= 'development';
^^^

SyntaxError: Unexpected token '??='
at Loader.moduleStrategy (internal/modules/esm/translators.js:141:18)
at async link (internal/modules/esm/module_job.js:42:21)
make: *** [serve-docs] Error 1

srdtrk · 2023-09-19T10:14:11Z

I think you need at least v16. I'm on v18 @damiannolan

damiannolan · 2023-09-19T10:15:16Z

Aye, thanks! Looks like it, just updating with nvm now 👍

damiannolan

I built and ran the docs locally. I haven't reviewed every file in the diff but happy to drop an ACK based off the content of the docs I checked out locally from this branch.

Thank you for all the work put into this! I much prefer the new docs ⭐ 🚀

srdtrk and others added 27 commits May 5, 2023 14:02

docs: migrate to docusaurus (#3511)

c1498a6

The following stack was used: - Docusaurus 2 - tailwindcss - postcss Min required node version is: 16.14 --------- Co-authored-by: colin axnér <[email protected]>

Merge remote-tracking branch 'origin' into feat/migrate-fully-to-docu…

4b1ee3c

…saurus

merge: remote-tracking branch 'origin' into feat/migrate-fully-to-doc…

9561b7f

…usaurus

merge: remote-tracking branch 'origin' into feat/migrate-fully-to-doc…

bbfe177

…usaurus

merge: fixing conficts

2973c63

merge: bringing back client docs

28030b7

merge: removing versions again

4080b85

merge: fix conflicts

91d694e

merge: remote branch 'origin' into feat/migrate-fully-to-docusaurus

d8a2838

fix: merge conflicts

a978934

fix: merge conflicts

b35bbb1

fix: merge conflicts

46e94ab

docs: implement versioned documentation (#3577)

65d7dd3

Merge branch 'main' into feat/migrate-fully-to-docusaurus

da1444c

# Conflicts: # CHANGELOG.md # docs/.vuepress/config.js # docs/docs/01-ibc/09-roadmap.md # docs/docs/05-migrations/10-v7-to-v8.md # docs/versions

merge: 'main' into 'feat/migrate-fully-to-docusaurus'

72cf0c1

merge: 'main' into 'feat/migrate-fully-to-docusaurus'

1114e96

feat: v7.3.x docs added

de3cffe

imp: improved Makefile for serving docs

421e15c

imp: checked out some problematic files

9e2ecc0

merge: 'main' into 'feat/migrate-fully-to-docusaurus'

5637d2d

fix: merge conflicts

d17f3cd

imp(docs): added versioned docs for v6.2.x

616fa53

ci: switched to docusaurus check and deploy workflows (#4688)

09cb304

* ci: switched to docusaurus check and deploy workflows * ci: added workflow_dispatch back to deploy-docs

merge: 'main' into 'feat/migrate-fully-to-docusaurus'

bcd0e2b

imp(lint): ignores all changelogs now

17be1a2

imp: ran linter

ad8e7d5

srdtrk added docs Improvements or additions to documentation github_actions Pull requests that update Github_actions code labels Sep 18, 2023

imp(makefile): improved build-docs

3486ecb

srdtrk requested review from damiannolan, chatton and DimitrisJim as code owners September 18, 2023 12:48

merge: branch 'main' into feat/migrate-fully-to-docusaurus

41e12d5

colin-axner approved these changes Sep 18, 2023

View reviewed changes

scripts/linting/lint-changed-md-files.sh Show resolved Hide resolved

srdtrk added 3 commits September 18, 2023 18:48

imp: improved workflows around markdownlint

5a2cc40

imp: improved workflows around markdownlint

3cb359a

merge: branch 'main' into feat/migrate-fully-to-docusaurus

30cd066

charleenfei approved these changes Sep 19, 2023

View reviewed changes

srdtrk added 2 commits September 19, 2023 13:05

imp(docs): added the new ibc assets

bb3f81c

merge: branch 'main' into feat/migrate-fully-to-docusaurus

907014e

srdtrk added 7 commits September 19, 2023 13:32

deps(docs): updated deps

cce23d1

style(docs): reorganized footer code

124d849

docs: fix cosmos-sdk broken links

d50668b

merge: 'main' into 'feat/migrate-fully-to-docusaurus'

af89d41

imp(docs): removed link from the footer logo

6f13552

imp(docs): improved footer

964064b

imp(docs): added a link to privacy policy

f827d07

damiannolan approved these changes Sep 19, 2023

View reviewed changes

srdtrk added 6 commits September 20, 2023 10:09

deps(docs): added 'npm run dev' script

dc0d523

merge: 'main' into 'feat/migrate-fully-to-docusaurus'

0dca0c7

imp(docs): apply review item

747c7ef

imp: ran 'make docs-lint'

5428c42

imp: added 'make tag-docs-version'

374594c

merge: branch 'main' into feat/migrate-fully-to-docusaurus

437ced6

srdtrk merged commit d39a825 into main Sep 20, 2023
60 checks passed

srdtrk deleted the feat/migrate-fully-to-docusaurus branch September 20, 2023 08:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(docs): migrate docs to docusaurus #4693

feat(docs): migrate docs to docusaurus #4693

srdtrk commented Sep 18, 2023 •

edited

Loading

colin-axner left a comment

charleenfei left a comment

charleenfei Sep 19, 2023

damiannolan commented Sep 19, 2023

srdtrk commented Sep 19, 2023

damiannolan commented Sep 19, 2023

damiannolan left a comment

feat(docs): migrate docs to docusaurus #4693

feat(docs): migrate docs to docusaurus #4693

Conversation

srdtrk commented Sep 18, 2023 • edited Loading

Description

Commit Message / Changelog Entry

colin-axner left a comment

Choose a reason for hiding this comment

charleenfei left a comment

Choose a reason for hiding this comment

charleenfei Sep 19, 2023

Choose a reason for hiding this comment

damiannolan commented Sep 19, 2023

srdtrk commented Sep 19, 2023

damiannolan commented Sep 19, 2023

damiannolan left a comment

Choose a reason for hiding this comment

srdtrk commented Sep 18, 2023 •

edited

Loading