Revamp of the documentation #1

samricotta · 2023-05-07T15:42:10Z

closes part of: cosmos/cosmos-sdk#15705

This closes the main parts of the above issue including:

Moving the documentation to a new repo
Landing page
Redesigning the categorisation of the documentation
Separating developer and user sections and adding validation and vision
Aligning with additional user journeys

The following parts will happen in additional PRs

Versioning
Deleting the current docs from cosmos/cosmos-sdk
Copying over changes from any changes in cosmos/cosmos-sdk using github workflows

Note: This PR must be merged last.

tac0turtle · 2023-05-10T10:18:22Z

docs/integrate/architecture/README.md

+sidebar_position: 1
+---
+
+# Architecture Decision Records (ADR)


this should stay in the sdk repo

tac0turtle · 2023-05-10T10:18:47Z

docs/integrate/modules/README.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 0


this should stay in the sdk

tac0turtle · 2023-05-10T10:19:14Z

docs/integrate/rfc/README.md

+sidebar_position: 1
+---
+
+# Requests for Comments


tac0turtle · 2023-05-10T10:19:53Z

docs/integrate/spec/SPEC_MODULE.md

@@ -0,0 +1,60 @@
+# Specification of Modules
+


ditto with this folder

julienrbrt · 2023-05-10T13:44:11Z

Agree with the comment Marko made above, and I would add the tooling documentation needs to stay in the SDK repo as well (so only some of the tooling).
The easy way to know what should stay in the SDK repo is to look at pre.sh: https://github.com/cosmos/cosmos-sdk/blob/117a426/docs/pre.sh. Everything that is copied must still live in the SDK repo, and be copied at build time here.

samricotta · 2023-05-10T13:55:45Z

Thanks @julienrbrt ! I personally believe it should all be in one place, just had a chat to marko (so the above comment is ood) and I'm going to try the following. Im working on a script that copies over any MD files that have had changes and replaces the same existing MD files on this repo using a GitHub Actions workflow which is triggered on any deployment in the main sdk repo.

julienrbrt · 2023-05-10T13:57:34Z

Thanks @julienrbrt ! I personally believe it should all be in one place, just had a chat to marko (so the above comment is ood) and I'm going to try the following. Im working on a script that copies over any MD files that have had changes and replaces the same existing MD files on this repo using a GitHub Actions workflow which is triggered on any deployment in the main sdk repo.

I see, so it won't be removed from the SDK right? If so that makes sense as well.

samricotta · 2023-05-10T14:00:21Z

They wont be removed, those files will remain but also live in this repo

julienrbrt

Can we have a PR with only the category and the docusaurus config and the action?
This is harder to review otherwise, my Google Chrome literally crashes viewing the diff.

This way there is as well a working base in the repo.

It would be nice as well if it can be configured simply without domain, so we can compare both website simultaneously (the current docs.cosmos.network and this one, at cosmos.github.io/cosmos-sdk-docs or another subdomain like docs-beta.cosmos.network)

julienrbrt · 2023-05-11T17:11:09Z

.github/workflows/deploy.yml

+      - run: yarn build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3


We should use the same action as in the SDK: https://github.com/cosmos/cosmos-sdk/blob/main/.github/workflows/deploy-docs.yml
There is no need to hardcode such thing in the action.

Yes to all the above, ill make those changes !

Can we have a PR with only the category and the docusaurus config and the action? This is harder to review otherwise, my Google Chrome literally crashes viewing the diff.

just to be clear you mean the category.json right?

julienrbrt · 2023-05-11T17:14:28Z

.github/workflows/deploy.yml

+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    env:
+      CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}


What token is that?

julienrbrt · 2023-05-11T17:14:52Z

.github/workflows/deploy.yml

+          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
+          # The GH actions bot is used by default if you didn't specify the two fields.
+          # You can swap them out with your own user credentials.
+          cname: docs.cosmos.network


This should be a file called CNAME at the root of the GH-pages branch

julienrbrt · 2023-05-15T14:26:31Z

go.mod

This file should be deleted.

julienrbrt

tACK, pending a few changes (gh actions and unnecessary go.mod)

julienrbrt · 2023-05-16T08:29:12Z

.github/workflows/deploy-docs.yml

+      - name: Build 🔧
+      - run: yarn install --frozen-lockfile
+      - run: yarn crowdin:sync
+      - name: Clean Crowdin Front Matter issues


What is Crodwin and what is that clean.sh script?
It isn't present in the repo.
From what I can see it is for translations? Given that the website is in english, I do not think we need this.

Yeah its just something specific from docusaurus, ill remove

julienrbrt · 2023-05-16T08:30:30Z

.github/workflows/deploy-docs.yml

+        with:
+          node-version: "16.x"
+
+      # npm install npm should be removed when https://github.com/npm/cli/issues/4942 is fixed


Suggested change

# npm install npm should be removed when https://github.com/npm/cli/issues/4942 is fixed

julienrbrt · 2023-05-16T08:31:16Z

.github/workflows/deploy-docs.yml

+      - main
+    paths:
+      - "docs/**"
+      - "x/**/*.md"


Suggested change

- "x/**/*.md"

There is no x folder here.

julienrbrt · 2023-05-16T08:34:09Z

docusaurus.config.js

For compatibilities issues, we really need to keep the redirections working. Many website depends on it, and it is even in governance proposal.
This can definitely be done in a follow-up, but all redirections present in the docusaurus config in the SDK should as well be ported there.
Moreover, redirections should be set from all the links that have changed from the current docs version to this version.

Ah i thought I mentioned in the description that the redirects section will be added to the versioning PR. So that piece of work will be added there. Thnx for checking up tho

* wip * Update glossary * review updates * update actions * remove path * Update deploy-docs.yml

samricotta force-pushed the sam/docs-revamp branch from 7a9d7d4 to 451b79b Compare May 8, 2023 11:33

wip

3e397bc

samricotta force-pushed the sam/docs-revamp branch from 9585019 to 3e397bc Compare May 9, 2023 10:37

Update glossary

06cd27c

samricotta force-pushed the sam/docs-revamp branch from 2bbf4e7 to 06cd27c Compare May 10, 2023 08:14

samricotta marked this pull request as ready for review May 10, 2023 08:21

tac0turtle reviewed May 10, 2023

View reviewed changes

docs/integrate/modules/README.md

@@ -0,0 +1,42 @@

---

sidebar_position: 0

Copy link

Member

tac0turtle May 10, 2023

Choose a reason for hiding this comment

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

this should stay in the sdk

tac0turtle reviewed May 10, 2023

View reviewed changes

docs/integrate/rfc/README.md

sidebar_position: 1

---

# Requests for Comments

Copy link

Member

tac0turtle May 10, 2023

Choose a reason for hiding this comment

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

ditto

tac0turtle reviewed May 10, 2023

View reviewed changes

docs/integrate/spec/SPEC_MODULE.md

@@ -0,0 +1,60 @@

# Specification of Modules

Copy link

Member

tac0turtle May 10, 2023

Choose a reason for hiding this comment

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

ditto with this folder

samricotta mentioned this pull request May 10, 2023

Docusaurus versioning #2

Merged

samricotta assigned aaronc May 11, 2023

julienrbrt requested changes May 11, 2023

View reviewed changes

julienrbrt reviewed May 15, 2023

View reviewed changes

go.mod Outdated

Copy link

Member

julienrbrt May 15, 2023

Choose a reason for hiding this comment

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

This file should be deleted.

samricotta reacted with thumbs up emoji

julienrbrt approved these changes May 15, 2023

View reviewed changes

samricotta added 2 commits May 15, 2023 22:47

review updates

130d141

update actions

680025c

julienrbrt reviewed May 16, 2023

View reviewed changes

samricotta added 2 commits May 17, 2023 10:38

remove path

45ef225

Update deploy-docs.yml

8f291cb

samricotta merged commit b2b498a into main Jun 11, 2023

samricotta added a commit that referenced this pull request Jun 11, 2023

Revamp of the documentation (#1)

eb470d3

* wip * Update glossary * review updates * update actions * remove path * Update deploy-docs.yml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Revamp of the documentation #1

Revamp of the documentation #1

samricotta commented May 7, 2023 •

edited

Loading

tac0turtle May 10, 2023

tac0turtle May 10, 2023

tac0turtle May 10, 2023

tac0turtle May 10, 2023

julienrbrt commented May 10, 2023

samricotta commented May 10, 2023 •

edited

Loading

julienrbrt commented May 10, 2023 •

edited

Loading

samricotta commented May 10, 2023

julienrbrt left a comment •

edited

Loading

julienrbrt May 11, 2023

samricotta May 11, 2023

samricotta May 15, 2023

julienrbrt May 11, 2023

julienrbrt May 11, 2023

julienrbrt May 15, 2023

julienrbrt left a comment •

edited

Loading

julienrbrt May 16, 2023

samricotta May 16, 2023

julienrbrt May 16, 2023

julienrbrt May 16, 2023

julienrbrt May 16, 2023

samricotta May 16, 2023

Revamp of the documentation #1

Revamp of the documentation #1

Conversation

samricotta commented May 7, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

julienrbrt commented May 10, 2023

samricotta commented May 10, 2023 • edited Loading

julienrbrt commented May 10, 2023 • edited Loading

samricotta commented May 10, 2023

julienrbrt left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

julienrbrt left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

samricotta commented May 7, 2023 •

edited

Loading

samricotta commented May 10, 2023 •

edited

Loading

julienrbrt commented May 10, 2023 •

edited

Loading

julienrbrt left a comment •

edited

Loading

julienrbrt left a comment •

edited

Loading