docs: Improve markdownlint configuration (#11104 )

## Description

Closes: #9404



---

### Author Checklist

*All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.*

I have...

- [x] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] added `!` to the type prefix if API or client breaking change
- [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [x] provided a link to the relevant issue or specification
- [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules)
- [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing)
- [ ] added a changelog entry to `CHANGELOG.md`
- [ ] included comments for [documenting Go code](https://blog.golang.org/godoc)
- [ ] updated the relevant documentation or specification
- [x] reviewed "Files changed" and left comments if necessary
- [x] confirmed all CI checks have passed

### Reviewers Checklist

*All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.*

I have...

- [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] confirmed `!` in the type prefix if API or client breaking change
- [ ] confirmed all author checklist items have been addressed 
- [ ] reviewed state machine logic
- [ ] reviewed API design and naming
- [ ] reviewed documentation is accurate
- [ ] reviewed tests and test coverage
- [ ] manually tested (if applicable)

2022-02-10 12:07:01 +00:00

3.3 KiB

Raw Blame History

ADR 002: SDK Documentation Structure

Context

There is a need for a scalable structure of the Cosmos SDK documentation. Current documentation includes a lot of non-related Cosmos SDK material, is difficult to maintain and hard to follow as a user.

Ideally, we would have:

All docs related to dev frameworks or tools live in their respective github repos (sdk repo would contain sdk docs, hub repo would contain hub docs, lotion repo would contain lotion docs, etc.)
All other docs (faqs, whitepaper, high-level material about Cosmos) would live on the website.

Decision

Re-structure the /docs folder of the Cosmos SDK github repo as follows:

docs/
├── README
├── intro/
├── concepts/
│   ├── baseapp
│   ├── types
│   ├── store
│   ├── server
│   ├── modules/
│   │   ├── keeper
│   │   ├── handler
│   │   ├── cli
│   ├── gas
│   └── commands
├── clients/
│   ├── lite/
│   ├── service-providers
├── modules/
├── spec/
├── translations/
└── architecture/

The files in each sub-folders do not matter and will likely change. What matters is the sectioning:

README: Landing page of the docs.
intro: Introductory material. Goal is to have a short explainer of the Cosmos SDK and then channel people to the resource they need. The Cosmos SDK tutorial will be highlighted, as well as the godocs.
concepts: Contains high-level explanations of the abstractions of the Cosmos SDK. It does not contain specific code implementation and does not need to be updated often. It is not an API specification of the interfaces. API spec is the godoc.
clients: Contains specs and info about the various Cosmos SDK clients.
spec: Contains specs of modules, and others.
modules: Contains links to godocs and the spec of the modules.
architecture: Contains architecture-related docs like the present one.
translations: Contains different translations of the documentation.

Website docs sidebar will only include the following sections:

README
intro
concepts
clients

architecture need not be displayed on the website.

Status

Accepted

Consequences

Positive

Much clearer organisation of the Cosmos SDK docs.
The /docs folder now only contains Cosmos SDK and gaia related material. Later, it will only contain Cosmos SDK related material.
Developers only have to update /docs folder when they open a PR (and not /examples for example).
Easier for developers to find what they need to update in the docs thanks to reworked architecture.
Cleaner vuepress build for website docs.
Will help build an executable doc (cf https://github.com/cosmos/cosmos-sdk/issues/2611)

Neutral

We need to move a bunch of deprecated stuff to /_attic folder.
We need to integrate content in docs/sdk/docs/core in concepts.
We need to move all the content that currently lives in docs and does not fit in new structure (like lotion, intro material, whitepaper) to the website repository.
Update DOCS_README.md

3.3 KiB Raw Blame History