-
Notifications
You must be signed in to change notification settings - Fork 625
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: implement versioned documentation #3577
docs: implement versioned documentation #3577
Conversation
…cing.md' -> '../../../architecture/adr-001-coin-source-tracing.md'
…ures as an example
…22-store-docs-for-past-versions
…22-store-docs-for-past-versions
Hi @srdtrk, is it possible to split up this pr? Smaller pr's would it make it easier to do reviews, catch issues, and merge code faster. With github's current review tooling, I think it's a big ask to have anyone from the team review a pr of this size and I suspect this pr will sit for a while longer if it isn't broken up |
Yeah, you're right @colin-axner, I'd like to talk about how I might break it in the next planning call. Also, I'm curious if it's possible for me to walk over the PR in a call since its size is due to me copy pasting and styling a large amount of old docs but the main content of the PR is not that large imo. |
If possible it would nice to see a PR with changes w/o any generated/copied files, and then some PRs that are just either adding generated or copied/linted files. |
…22-store-docs-for-past-versions
I've removed the unnecessary linter changes. Let me know if this is easier to review @colin-axner |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is awesome, @srdtrk! I just have a couple of questions about the process for creating documentation for new releases, but I think I just need to do it once myself and it will be fine.
- [ ] Add new release branch to [`docs/versions`](https://github.com/cosmos/ibc-go/blob/main/docs/versions) file. | ||
- [ ] Add `label` and `key` to `versions` array in [`config.js`](https://github.com/cosmos/ibc-go/blob/main/docs/.vuepress/config.js#L62). | ||
- [ ] Update docs site: | ||
- [ ] If the release is occurring on the main branch, on the latest version, then run `npm run docusaurus docs:version vX.Y.Z` in the `docs/` directory. (where `X.Y.Z` is the new version number) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We always release from a release/vx.y.z
branch, never from main. Would this flow still work? Like, can I run npm run docusaurus docs:version vX.Y.Z
in the docs/
folder in release/vX.Y.Z
branch?
- [ ] Add `label` and `key` to `versions` array in [`config.js`](https://github.com/cosmos/ibc-go/blob/main/docs/.vuepress/config.js#L62). | ||
- [ ] Update docs site: | ||
- [ ] If the release is occurring on the main branch, on the latest version, then run `npm run docusaurus docs:version vX.Y.Z` in the `docs/` directory. (where `X.Y.Z` is the new version number) | ||
- [ ] If the release is occurring on an older release branch, then make a PR to the main branch called `docs: new release vX.Y.Z` doing the following: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
x.y.z
is here the previous (existing) release or the new one? Sorry, it was not clear to me...
- Follow Google developer documentation [style guide](https://developers.google.com/style). | ||
- Check the meaning of words in Microsoft's [A-Z word list and term collections](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) (use the search input!). | ||
- We recommend using RFC keywords in user documentation (lowercase). The RFC keywords are: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). | ||
- Lint the markdown files for documentation with [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli). Run `make docs-lint` (you will need to have `markdownlint-cli` installed, so please follow the [installation instructions](https://github.com/igorshubovych/markdownlint-cli#installation)). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I guess the reference to markdownlint-cli
here will be updated with this other PR, right?
channeltypes "github.com/cosmos/ibc-go/v6/modules/core/04-channel/types" | ||
porttypes "github.com/cosmos/ibc-go/v6/modules/core/05-port/types" | ||
"github.com/cosmos/ibc-go/v6/modules/core/exported" | ||
sdk "github.com/cosmos/cosmos-sdk/types" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can the linter format the code blocks with 2-space tabs? If it could, it would make me sooooo happy.
@@ -32,7 +32,7 @@ module correctly corresponding to the listed steps. | |||
|
|||
:::note | |||
|
|||
## Pre-requisites Readings | |||
## Pre-requisite readings |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And can the linter make sure that headings use only capital letter on the first word? That would be like the best thing since sliced bread.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I dunno man, sliced bread is pretty good if you ask me
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
first pass few nits
@@ -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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
out of curiousity, are we actually monitoring this email address? cc @womensrights @crodriguezvega
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Checking!
* [ICS 20, ICS 27 implementations of the CallbackPacketData interface](https://github.com/cosmos/ibc-go/pull/3287) | ||
- [Original issue](https://github.com/cosmos/ibc-go/issues/1660) | ||
- [CallbackPacketData interface implementation](https://github.com/cosmos/ibc-go/pull/3287) | ||
- [ICS 20, ICS 27 implementations of the CallbackPacketData interface](https://github.com/cosmos/ibc-go/pull/3287) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
will we update these links to the latest ADR8 PR?
* application logic which wraps ICS 27 packet sends do not need to be associated with the authentication logic | ||
- a default authentication module would enable more usage of ICS 27 | ||
- generic authentication modules should be capable of authenticating an interchain account registration | ||
- application logic which wraps ICS 27 packet sends do not need to be associated with the authentication logic |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- application logic which wraps ICS 27 packet sends do not need to be associated with the authentication logic | |
- application logic which wraps ICS 27 packet sends does not need to be associated with the authentication logic |
} | ||
} | ||
``` | ||
|
||
See [ADR-03](../../architecture/adr-003-ics27-acknowledgement.md/#next-major-version-format) for more information or the [corrresponding documentation about authentication modules](../02-apps/01-interchain-accounts/03-auth-modules.md#onacknowledgementpacket). | ||
See [ADR-03](/architecture/adr-003-ics27-acknowledgement#next-major-version-format) for more information or the [corrresponding documentation about authentication modules](../02-apps/02-interchain-accounts/03-auth-modules.md#onacknowledgementpacket). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See [ADR-03](/architecture/adr-003-ics27-acknowledgement#next-major-version-format) for more information or the [corrresponding documentation about authentication modules](../02-apps/02-interchain-accounts/03-auth-modules.md#onacknowledgementpacket). | |
See [ADR-03](/architecture/adr-003-ics27-acknowledgement#next-major-version-format) for more information or the [corresponding documentation about authentication modules](../02-apps/02-interchain-accounts/03-auth-modules.md#onacknowledgementpacket). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
thank you so much @srdtrk for taking care of this docs work, i know it's not the most fun task!
i think we should go ahead and wrap up/merge this pr, and we can handle updating the versions ie 7.2.0 in a later pr.
@@ -46,4 +46,4 @@ To wrap Apalache docker image into an executable you might create the following | |||
docker run --rm -v $(pwd):/var/apalache apalache/mc $@ | |||
``` | |||
|
|||
In case of any questions please don't hesitate to contact Andrey Kuprianov ([email protected]). | |||
In case of any questions please don't hesitate to contact Andrey Kuprianov (<[email protected]>). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
just wondering if we still need these docs in here, not sure about latest state of Apalache?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Apalache is still in active development, so I think it's ok to leave this here.
Thank you, @srdtrk for taking of this migration, and @charleenfei for reviewing. Let's merge to unblock the rest of the work and open separate PRs for further improvements. |
* docs: migrate to docusaurus (#3511) 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: fixing conficts * merge: bringing back client docs * merge: removing versions again * merge: fix conflicts * fix: merge conflicts * fix: merge conflicts * fix: merge conflicts * docs: implement versioned documentation (#3577) * docs: workflow and linter improvements (#3805) * 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]> * feat: v7.3.x docs added * imp: improved Makefile for serving docs * imp: checked out some problematic files * fix: merge conflicts * imp(docs): added versioned docs for v6.2.x * ci: switched to docusaurus check and deploy workflows (#4688) * ci: switched to docusaurus check and deploy workflows * ci: added workflow_dispatch back to deploy-docs * imp(lint): ignores all changelogs now * imp: ran linter * imp(makefile): improved build-docs * fix(docs): broken links * imp: improved workflows around markdownlint * imp: improved workflows around markdownlint * imp(docs): added the new ibc assets * deps(docs): updated deps * style(docs): reorganized footer code * docs: fix cosmos-sdk broken links * imp(docs): removed link from the footer logo * imp(docs): improved footer * imp(docs): added a link to privacy policy * deps(docs): added 'npm run dev' script * imp(docs): apply review item * imp: ran 'make docs-lint' * imp: added 'make tag-docs-version' --------- Co-authored-by: colin axnér <[email protected]> Co-authored-by: Carlos Rodriguez <[email protected]> Co-authored-by: Charly <[email protected]>
Description
Overview
feat
(latermain
) branch:v7.0.0
v6.1.0
v5.3.0
v4.4.0
link-check
workflow now supports docusaurus linksand is only activated upon.md
file modifications. (excluding.github/
directory)New(moved to another PR)markdown-lint
workflow has been addedmarkdownlint
tomarkdownlint-cli2
in this repo. (Makefile is updated accordingly).md
file has been modified (not including.github/
directory)..markdownlint-cli2.jsonc
, this tool also continues to use.markdownlint.jsonc
.markdownlint.jsonc
to address: Consider using a linter for markdown files #3543.closes: #3522, #3623
addresses: #3488
Changes
Structural Changes
This update introduces versioned docs. Here, I will describe the structural changes that this feature brings, to learn more about versioning in this repo, go to
docs/README.md
.Two new directories and one new file was added to
docs/
to enable versioning,Content Changes:
Commit Message / Changelog Entry
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.
Code follows the module structure standards and Go style guide.Wrote unit and integration tests.docs/
) or specification (x/<module>/spec/
).Added relevantgodoc
comments.Re-reviewedFiles changed
in the Github PR explorer.ReviewCodecov Report
in the comment section below once CI passes.