From a3b8b7fcc92ba5656010146b587bea2ba1e5b094 Mon Sep 17 00:00:00 2001 From: Marko Date: Wed, 19 Oct 2022 14:38:36 +0200 Subject: [PATCH] docs: fix tooling (#13593) * fix docs * some more fixes * some more fixes * some more fixes * move spec to 12 * fix * fix * Update docs/docs/tooling/00-protobuf.md Co-authored-by: Julien Robert Co-authored-by: Julien Robert --- cosmovisor/README.md | 2 +- docs/architecture/_category_.json | 2 +- docs/docs/tooling/00-protobuf.md | 21 +++++++++++---------- docs/docs/tooling/README.md | 7 +++++-- docs/docs/tooling/_category_.json | 2 +- docs/post.sh | 4 ++-- docs/spec/_category_.json | 2 +- 7 files changed, 22 insertions(+), 18 deletions(-) diff --git a/cosmovisor/README.md b/cosmovisor/README.md index 1280530328..76eba133cb 100644 --- a/cosmovisor/README.md +++ b/cosmovisor/README.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 1 --- # Cosmovisor diff --git a/docs/architecture/_category_.json b/docs/architecture/_category_.json index b25a8cb7a7..d138de900c 100644 --- a/docs/architecture/_category_.json +++ b/docs/architecture/_category_.json @@ -2,4 +2,4 @@ "label": "ADRs", "position": 10, "link": null -} \ No newline at end of file +} diff --git a/docs/docs/tooling/00-protobuf.md b/docs/docs/tooling/00-protobuf.md index 1e79c44220..adbe2721ea 100644 --- a/docs/docs/tooling/00-protobuf.md +++ b/docs/docs/tooling/00-protobuf.md @@ -29,8 +29,9 @@ https://github.com/cosmos/cosmos-sdk/blob/10e8aadcad3a30dda1d6163c39c9f86b4a877e At the root level directory a workspace is defined using [buf workspaces](https://docs.buf.build/configuration/v1/buf-work-yaml). This helps if there are one or more protobuf containing directories in your project. Cosmos SDK example: + ```go reference -https://github.com/cosmos/cosmos-sdk/blob/78c463c2130b18d823f7713f336a9b76e7b6d8b8/buf.work.yaml#L6-L9 +https://github.com/cosmos/cosmos-sdk/blob/main/buf.work.yaml#L6-L9 ``` ### Proto Directory @@ -56,7 +57,7 @@ The above diagram all the files and directories within the Cosmos SDK `proto/` d `buf.gen.gogo.yaml` defines how the protobuf files should be generated for use with in the module. This file uses [gogoproto](https://github.com/gogo/protobuf), a separate generator from the google go-proto generator that makes working with various objects more ergonomic, and it has more performant encode and decode steps ```go reference -https://github.com/cosmos/cosmos-sdk/blob/78c463c2130b18d823f7713f336a9b76e7b6d8b8/proto/buf.gen.gogo.yaml#L1-l9 +https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.gen.gogo.yaml#L1-l9 ``` > Example of how to define `gen` files can be found [here](https://docs.buf.build/tour/generate-go-code) @@ -66,17 +67,17 @@ https://github.com/cosmos/cosmos-sdk/blob/78c463c2130b18d823f7713f336a9b76e7b6d8 `buf.gen.pulsar.yaml` defines how protobuf files should be generated using the [new golang apiv2 of protobuf](https://go.dev/blog/protobuf-apiv2). This generator is used instead of the google go-proto generator because it has some extra helpers for Cosmos SDK applications and will have more performant encode and decode than the google go-proto generator. You can follow the development of this generator [here](https://github.com/cosmos/cosmos-proto). ```go reference -https://github.com/cosmos/cosmos-sdk/blob/78c463c2130b18d823f7713f336a9b76e7b6d8b8/proto/buf.gen.pulsar.yaml#L1-L18 +https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.gen.pulsar.yaml#L1-L18 ``` > Example of how to define `gen` files can be found [here](https://docs.buf.build/tour/generate-go-code) #### `buf.gen.swagger.yaml` -`buf.gen.swagger.yaml` generates the swagger documentation for the query and messages of the chain. This will only define the REST API end points that were defined in the query and msg servers. You can find examples of this [here](https://github.com/cosmos/cosmos-sdk/blob/78c463c2130b18d823f7713f336a9b76e7b6d8b8/proto/cosmos/bank/v1beta1/query.proto#L19) +`buf.gen.swagger.yaml` generates the swagger documentation for the query and messages of the chain. This will only define the REST API end points that were defined in the query and msg servers. You can find examples of this [here](https://github.com/cosmos/cosmos-sdk/blob/main/proto/cosmos/bank/v1beta1/query.proto#L19) ```go reference -https://github.com/cosmos/cosmos-sdk/blob/78c463c2130b18d823f7713f336a9b76e7b6d8b8/proto/buf.gen.swagger.yaml#L1-L6 +https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.gen.swagger.yaml#L1-L6 ``` > Example of how to define `gen` files can be found [here](https://docs.buf.build/tour/generate-go-code) @@ -86,21 +87,21 @@ https://github.com/cosmos/cosmos-sdk/blob/78c463c2130b18d823f7713f336a9b76e7b6d8 This is a autogenerated file based off the dependencies required by the `.gen` files. There is no need to copy the current one. If you depend on cosmos-sdk proto definitions a new entry for the Cosmos SDK will need to be provided. The dependency you will need to use is `buf.build/cosmos/cosmos-sdk`. ```go reference -https://github.com/cosmos/cosmos-sdk/blob/78c463c2130b18d823f7713f336a9b76e7b6d8b8/proto/buf.lock#L1-L16 +https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.lock#L1-L16 ``` #### `buf.yaml` -`buf.yaml` defines the [name of your package](https://github.com/cosmos/cosmos-sdk/blob/78c463c2130b18d823f7713f336a9b76e7b6d8b8/proto/buf.yaml#L3), which [breakage checker](https://docs.buf.build/tour/detect-breaking-changes) to use and how to [lint your protobuf files](https://docs.buf.build/tour/lint-your-api). +`buf.yaml` defines the [name of your package](https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.yaml#L3), which [breakage checker](https://docs.buf.build/tour/detect-breaking-changes) to use and how to [lint your protobuf files](https://docs.buf.build/tour/lint-your-api). ```go reference -https://github.com/cosmos/cosmos-sdk/blob/78c463c2130b18d823f7713f336a9b76e7b6d8b8/proto/buf.yaml#L1-L24 +https://github.com/cosmos/cosmos-sdk/blob/main/proto/buf.yaml#L1-L24 ``` We use a variety of linters for the Cosmos SDK protobuf files. The repo also checks this in ci. -A reference to the github actions can be found [here](https://github.com/cosmos/cosmos-sdk/blob/78c463c2130b18d823f7713f336a9b76e7b6d8b8/.github/workflows/proto.yml#L1-L32) +A reference to the github actions can be found [here](https://github.com/cosmos/cosmos-sdk/blob/main/.github/workflows/proto.yml#L1-L32) ```go reference -https://github.com/cosmos/cosmos-sdk/blob/78c463c2130b18d823f7713f336a9b76e7b6d8b8/.github/workflows/proto.yml#L1-L32 +https://github.com/cosmos/cosmos-sdk/blob/main/.github/workflows/proto.yml#L1-L32 ``` diff --git a/docs/docs/tooling/README.md b/docs/docs/tooling/README.md index 342a781d29..53b76196e1 100644 --- a/docs/docs/tooling/README.md +++ b/docs/docs/tooling/README.md @@ -1,7 +1,10 @@ --- -sidebar_position: 1 +sidebar_position: 0 --- -# Tooling +# Tools This section provides documentation on various tooling used in development of a Cosmos SDK chain, operating a node and testing. + +- [Protocol Buffers](./00-protobuf.md) +- [Cosmovisor](./01-cosmovisor.md) diff --git a/docs/docs/tooling/_category_.json b/docs/docs/tooling/_category_.json index d13637648f..7c6ec93d4a 100644 --- a/docs/docs/tooling/_category_.json +++ b/docs/docs/tooling/_category_.json @@ -1,5 +1,5 @@ { "label": "Tooling", - "position": 10, + "position": 9, "link": null } diff --git a/docs/post.sh b/docs/post.sh index edcdf42939..6ebd2a9eab 100755 --- a/docs/post.sh +++ b/docs/post.sh @@ -1,8 +1,8 @@ #!/usr/bin/env bash rm -rf docs/modules -rm -rf docs/run-node/06-cosmovisor.md +rm -rf docs/tooling/01-cosmovisor.md rm -rf docs/building-apps/01-depinject.md rm -rf docs/architecture rm -rf docs/spec -rm -rf versioned_docs versioned_sidebars versions.json \ No newline at end of file +rm -rf versioned_docs versioned_sidebars versions.json diff --git a/docs/spec/_category_.json b/docs/spec/_category_.json index 5863df7714..e77f62999b 100644 --- a/docs/spec/_category_.json +++ b/docs/spec/_category_.json @@ -2,4 +2,4 @@ "label": "Specifications", "position": 11, "link": null -} \ No newline at end of file +}