Skip to content

Commit

Permalink
docs: improve documentation navigation and redirection (cosmos#13455)
Browse files Browse the repository at this point in the history
  • Loading branch information
@julienrbrt
julienrbrt authored Oct 6, 2022
1 parent ff39d24 commit 74ce07e
Show file tree
Hide file tree
Showing 43 changed files with 300 additions and 12,936 deletions.
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/module-readiness-checklist.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ The module **should not** be included in any Release Candidate tag until it has

- [ ] API audit (at least 1 person) (@assignee)
- [ ] Are Msg and Query methods and types well-named and organized?
- [ ] Is everything well documented (inline godoc as well as [`/spec/` folder](https://github.com/cosmos/cosmos-sdk/blob/main/docs/spec/SPEC-SPEC.md) in module directory)
- [ ] Is everything well documented (inline godoc as well as the spec [README.md](https://github.com/cosmos/cosmos-sdk/blob/main/docs/spec/SPEC-SPEC.md) in module directory)
- [ ] State machine audit (at least 2 people) (@assignee1, @assignee2)
- [ ] Read through MsgServer code and verify correctness upon visual inspection
- [ ] Ensure all state machine code which could be confusing is properly commented
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@ If you open a PR on the Cosmos SDK, it is mandatory to update the relevant docum

* If your change relates to the core SDK (baseapp, store, ...), be sure to update the content in `docs/basics/`, `docs/core/` and/or `docs/building-modules/` folders.
* If your changes relate to the core of the CLI (not specifically to module's CLI/Rest), then modify the content in the `docs/run-node/` folder.
* If your changes relate to a module, then be sure to update the module's spec in `x/{moduleName}/docs/spec/`.
* If your changes relate to a module, then be sure to update the module's spec in `x/{moduleName}/README.md`.

When writing documentation, follow the [Documentation Writing Guidelines](./docs/DOC_WRITING_GUIDELINES.md).

Expand Down
1 change: 0 additions & 1 deletion Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@ DOCS_DOMAIN=docs.cosmos.network
# RocksDB is a native dependency, so we don't assume the library is installed.
# Instead, it must be explicitly enabled and we warn when it is not.
ENABLE_ROCKSDB ?= false
GOWORK = off # we disable the `go.work` for consistency with our CI

# process build tags
build_tags = netgo
Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ parent:
<h1> Cosmos SDK </h1>
</div>

![banner](docs/cosmos-sdk-image.jpg)
![banner](docs/assets/banner.jpg)

<div align="center">
<a href="https://github.com/cosmos/cosmos-sdk/blob/main/LICENSE">
Expand Down
12 changes: 6 additions & 6 deletions depinject/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Concretely `SimApp` uses the implementation in `x/auth`, but this design allows

Given the following types

```golang
```go
package duck

type Duck interface {
Expand All @@ -76,7 +76,7 @@ type Pond struct {

This usage

```golang
```go
var pond Pond

depinject.Inject(
Expand All @@ -91,7 +91,7 @@ depinject.Inject(
results in an *implicit* binding of `Duck` to `Mallard`. This works because there is only one implementation of `Duck`
in the container. However, adding a second provider of `Duck` will result in an error:

```golang
```go
var pond Pond

depinject.Inject(
Expand All @@ -110,7 +110,7 @@ A specific binding preference for `Duck` is required.

In the above situation registering a binding for a given interface binding may look like

```golang
```go
depinject.Inject(
depinject.Configs(
depinject.BindInterface(
Expand Down Expand Up @@ -174,15 +174,15 @@ be printed to stderr and a rendering of the dependency graph in Graphviz DOT for
`debug_container.dot`.
Here is an example Graphviz rendering of a successful build of a dependency graph:
![Graphviz Example](./testdata/example.svg)
![Graphviz Example](https://raw.githubusercontent.com/cosmos/cosmos-sdk/ff39d243d421442b400befcd959ec3ccd2525154/depinject/testdata/example.svg)
Rectangles represent functions, ovals represent types, rounded rectangles represent modules and the single hexagon
represents the function which called `Build`. Black-colored shapes mark functions and types that were called/resolved
without an error. Gray-colored nodes mark functions and types that could have been called/resolved in the container but
were left unused.
Here is an example Graphviz rendering of a dependency graph build which failed:
![Graphviz Error Example](./testdata/example_error.svg)
![Graphviz Error Example](https://raw.githubusercontent.com/cosmos/cosmos-sdk/ff39d243d421442b400befcd959ec3ccd2525154/depinject/testdata/example_error.svg)
Graphviz DOT files can be converted into SVG's for viewing in a web browser using the `dot` command-line tool, ex:
Expand Down
171 changes: 104 additions & 67 deletions docs/.vuepress/config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,48 @@ module.exports = {
title: "Cosmos SDK",
locales: {
"/": {
lang: "en-US"
lang: "en-US",
},
},
base: process.env.VUEPRESS_BASE || "/",
head: [
['link', { rel: "apple-touch-icon", sizes: "180x180", href: "/apple-touch-icon.png" }],
['link', { rel: "icon", type: "image/png", sizes: "32x32", href: "/favicon-32x32.png" }],
['link', { rel: "icon", type: "image/png", sizes: "16x16", href: "/favicon-16x16.png" }],
['link', { rel: "manifest", href: "/site.webmanifest" }],
['meta', { name: "msapplication-TileColor", content: "#2e3148" }],
['meta', { name: "theme-color", content: "#ffffff" }],
['link', { rel: "icon", type: "image/svg+xml", href: "/favicon-svg.svg" }],
['link', { rel: "apple-touch-icon-precomposed", href: "/apple-touch-icon-precomposed.png" }],
[
"link",
{
rel: "apple-touch-icon",
sizes: "180x180",
href: "/apple-touch-icon.png",
},
],
[
"link",
{
rel: "icon",
type: "image/png",
sizes: "32x32",
href: "/favicon-32x32.png",
},
],
[
"link",
{
rel: "icon",
type: "image/png",
sizes: "16x16",
href: "/favicon-16x16.png",
},
],
["link", { rel: "manifest", href: "/site.webmanifest" }],
["meta", { name: "msapplication-TileColor", content: "#2e3148" }],
["meta", { name: "theme-color", content: "#ffffff" }],
["link", { rel: "icon", type: "image/svg+xml", href: "/favicon-svg.svg" }],
[
"link",
{
rel: "apple-touch-icon-precomposed",
href: "/apple-touch-icon-precomposed.png",
},
],
],
themeConfig: {
repo: "cosmos/cosmos-sdk",
Expand All @@ -27,28 +56,28 @@ module.exports = {
algolia: {
id: "BH4D9OD16A",
key: "ac317234e6a42074175369b2f42e9754",
index: "cosmos-sdk"
index: "cosmos-sdk",
},
versions: [
{
"label": "v0.44",
"key": "v0.44"
label: "v0.45",
key: "v0.45",
},
{
"label": "v0.45",
"key": "v0.45"
label: "v0.46",
key: "v0.46",
},
{
"label": "v0.46",
"key": "v0.46"
label: "v0.47 - Twilight",
key: "v0.47",
},
{
"label": "main",
"key": "main"
}
label: "main",
key: "main",
},
],
topbar: {
banner: false
banner: false,
},
sidebar: {
auto: true,
Expand All @@ -59,28 +88,28 @@ module.exports = {
{
title: "Modules",
directory: true,
path: "/modules"
}
]
path: "/modules",
},
],
},
{
title: "Resources",
children: [
{
title: "Tutorials",
path: "https://tutorials.cosmos.network"
path: "https://tutorials.cosmos.network",
},
{
title: "SDK API Reference",
path: "https://pkg.go.dev/github.com/cosmos/cosmos-sdk"
path: "https://pkg.go.dev/github.com/cosmos/cosmos-sdk",
},
{
title: "REST API Spec",
path: "https://cosmos.network/rpc/"
}
]
}
]
path: "https://cosmos.network/rpc/",
},
],
},
],
},
gutter: {
title: "Help & Support",
Expand All @@ -89,120 +118,128 @@ module.exports = {
title: "Discord",
text: "Chat with Cosmos developers on Discord.",
url: "https://discordapp.com/channels/669268347736686612",
bg: "linear-gradient(225.11deg, #2E3148 0%, #161931 95.68%)"
bg: "linear-gradient(225.11deg, #2E3148 0%, #161931 95.68%)",
},
forum: {
title: "Cosmos SDK Forum",
text: "Join the SDK Developer Forum to learn more.",
url: "https://forum.cosmos.network/",
bg: "linear-gradient(225deg, #46509F -1.08%, #2F3564 95.88%)",
logo: "cosmos"
logo: "cosmos",
},
github: {
title: "Found an Issue?",
text: "Help us improve this page by suggesting edits on GitHub."
}
text: "Help us improve this page by suggesting edits on GitHub.",
},
},
footer: {
question: {
text: "Chat with Cosmos developers in <a href='https://discord.gg/cosmosnetwork' target='_blank'>Discord</a> or reach out on the <a href='https://forum.cosmos.network/c/tendermint' target='_blank'>SDK Developer Forum</a> to learn more."
text:
"Chat with Cosmos developers in <a href='https://discord.gg/cosmosnetwork' target='_blank'>Discord</a> or reach out on the <a href='https://forum.cosmos.network/c/tendermint' target='_blank'>SDK Developer Forum</a> to learn more.",
},
logo: "/logo-bw.svg",
textLink: {
text: "cosmos.network",
url: "https://cosmos.network"
url: "https://cosmos.network",
},
services: [
{
service: "medium",
url: "https://blog.cosmos.network/"
url: "https://blog.cosmos.network/",
},
{
service: "twitter",
url: "https://twitter.com/cosmos"
url: "https://twitter.com/cosmos",
},
{
service: "linkedin",
url: "https://www.linkedin.com/company/tendermint/"
url: "https://www.linkedin.com/company/interchain-gmbh/",
},
{
service: "reddit",
url: "https://reddit.com/r/cosmosnetwork"
url: "https://reddit.com/r/cosmosnetwork",
},
{
service: "telegram",
url: "https://t.me/cosmosproject"
url: "https://t.me/cosmosproject",
},
{
service: "youtube",
url: "https://www.youtube.com/c/CosmosProject"
}
url: "https://www.youtube.com/c/CosmosProject",
},
],
smallprint: "The development of the Cosmos SDK is led primarily by [Interchain Core Teams](https://interchain.io/ecosystem). Funding for this development comes primarily from the Interchain Foundation, a Swiss non-profit.",
smallprint:
"The development of the Cosmos SDK is led primarily by [Interchain Core Teams](https://interchain.io/ecosystem). Funding for this development comes primarily from the Interchain Foundation, a Swiss non-profit.",
links: [
{
title: "Documentation",
children: [
{
title: "Cosmos Hub",
url: "https://hub.cosmos.network"
url: "https://hub.cosmos.network",
},
{
title: "Tendermint Core",
url: "https://docs.tendermint.com"
url: "https://docs.tendermint.com",
},
{
title: "IBC-Go",
url: "https://ibc.cosmos.network"
title: "IBC Go",
url: "https://ibc.cosmos.network",
},
]
],
},
{
title: "Community",
children: [
{
title: "Cosmos blog",
url: "https://blog.cosmos.network"
url: "https://blog.cosmos.network",
},
{
title: "Forum",
url: "https://forum.cosmos.network"
url: "https://forum.cosmos.network",
},
{
title: "Chat",
url: "https://discord.gg/cosmosnetwork"
}
]
url: "https://discord.gg/cosmosnetwork",
},
],
},
{
title: "Contributing",
children: [
{
title: "Contributing to the docs",
url:
"https://github.com/cosmos/cosmos-sdk/blob/main/docs/DOCS_README.md"
"https://github.com/cosmos/cosmos-sdk/blob/main/docs/DOCS_README.md",
},
{
title: "Source code on GitHub",
url: "https://github.com/cosmos/cosmos-sdk/"
}
]
}
]
}
url: "https://github.com/cosmos/cosmos-sdk/",
},
],
},
],
},
},
plugins: [
[
"@vuepress/google-analytics",
{
ga: "UA-51029217-2"
}
ga: "UA-51029217-2",
},
],
[
"@vuepress/html-redirect",
{
countdown: 0,
},
],
[
"sitemap",
{
hostname: "https://docs.cosmos.network"
}
]
]
hostname: "https://docs.cosmos.network",
},
],
],
};
Loading

0 comments on commit 74ce07e

Please sign in to comment.