Skip to content
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

Conversation

srdtrk
Copy link
Member

@srdtrk srdtrk commented May 15, 2023

Description

Overview

  • Docs for the following IBC-go versions are now stored in the feat (later main) branch:
    • v7.0.0
    • v6.1.0
    • v5.3.0
    • v4.4.0
  • The link-check workflow now supports docusaurus links and is only activated upon .md file modifications. (excluding .github/ directory)
  • New markdown-lint workflow has been added (moved to another PR)
  • Makefile and docs deployment workflows have been updated
  • Added search bar to docs

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,

ibc-go/docs/
├── versions.json          # file to indicate what versions are available
├── versioned_docs/
│   ├── version-v4.4.0/    # markdown files and categories for v4.4.0 are stored here
│   ├── version-v5.3.0/
│   ├── version-v6.1.0/
│   └── version-v7.0.0/
├── versioned_sidebars/    # sidebars for the versions are kept here
│   ├── version-v4.4.0-sidebars.json
│   ├── version-v5.3.0-sidebars.json
│   ├── version-v6.1.0-sidebars.json
│   └── version-v7.0.0-sidebars.json
...

Content Changes:

  • ADRs' README.md is not missing some ADRs anymore.
  • Transfer is now the first IBC app.
  • README.md now also includes documentation guidelines. (DOCS_GUIDELINES.md no longer exists)
  • Fixes various styling errors and broken links.

Commit Message / Changelog Entry

docs: implement versioned documentation and update workflows

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.

srdtrk added 30 commits May 6, 2023 19:50
…cing.md' -> '../../../architecture/adr-001-coin-source-tracing.md'
@colin-axner
Copy link
Contributor

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

@srdtrk
Copy link
Member Author

srdtrk commented May 29, 2023

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.

@chatton
Copy link
Contributor

chatton commented May 30, 2023

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.

@srdtrk
Copy link
Member Author

srdtrk commented Jun 9, 2023

I've removed the unnecessary linter changes. Let me know if this is easier to review @colin-axner

@srdtrk srdtrk mentioned this pull request Jun 9, 2023
12 tasks
@srdtrk srdtrk changed the title docs: implement versioned documentation and update workflows docs: implement versioned documentation Jun 12, 2023
Copy link
Contributor

@crodriguezvega crodriguezvega left a 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)
Copy link
Contributor

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:
Copy link
Contributor

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)).
Copy link
Contributor

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"
Copy link
Contributor

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
Copy link
Contributor

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.

Copy link
Member

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

Copy link
Contributor

@charleenfei charleenfei left a 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.
Copy link
Contributor

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

Copy link
Contributor

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)
Copy link
Contributor

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- 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).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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).

Copy link
Contributor

@charleenfei charleenfei left a 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]>).
Copy link
Contributor

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?

Copy link
Contributor

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.

@crodriguezvega
Copy link
Contributor

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.

@crodriguezvega crodriguezvega merged commit 65d7dd3 into feat/migrate-fully-to-docusaurus Jul 4, 2023
@crodriguezvega crodriguezvega deleted the serdar/issue#3522-store-docs-for-past-versions branch July 4, 2023 11:20
srdtrk added a commit that referenced this pull request Sep 20, 2023
* 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]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Archived in project
Development

Successfully merging this pull request may close these issues.

7 participants