2018-12-17 09:22:11 -08:00
# Updating the docs
2018-11-14 11:44:17 -08:00
2019-12-10 06:29:46 -08:00
If you want to open a PR on the Cosmos SDK to update the documentation, please follow the guidelines in the [`CONTRIBUTING.md` ](https://github.com/cosmos/cosmos-sdk/tree/master/CONTRIBUTING.md#updating-documentation )
## Translating
- Docs translations live in a `docs/country-code/` folder, where `country-code` stands for the country code of the language used (`cn` for Chinese, `kr` for Korea, `fr` for France, ...).
2020-11-27 04:57:14 -08:00
- Always translate content living on `master` .
2019-12-10 06:29:46 -08:00
- Only content under `/docs/intro/` , `/docs/basics/` , `/docs/core/` , `/docs/building-modules/` and `docs/interfaces` needs to be translated, as well as `docs/README.md` . It is also nice (but not mandatory) to translate `/docs/spec/` .
- Specify the release/tag of the translation in the README of your translation folder. Update the release/tag each time you update the translation.
2018-11-14 11:44:17 -08:00
## Docs Build Workflow
2018-07-16 11:19:11 -07:00
2019-09-03 05:27:23 -07:00
The documentation for the Cosmos SDK is hosted at https://cosmos.network/docs/
2018-07-16 11:19:11 -07:00
2018-09-19 10:24:31 -07:00
built from the files in this (`/docs`) directory for
2019-08-01 11:02:35 -07:00
[master ](https://github.com/cosmos/cosmos-sdk/tree/master/docs ).
2018-07-16 11:19:11 -07:00
2018-11-14 11:44:17 -08:00
### How It Works
2018-07-16 11:19:11 -07:00
2019-09-03 05:27:23 -07:00
There is a CircleCI job listening for changes in the `/docs` directory, on
the `master` branch. Any updates to files in this directory
on that branch will automatically trigger a website deployment. Under the hood,
2018-12-17 09:22:11 -08:00
the private website repository has a `make build-docs` target consumed by a CircleCI job in that repo.
2018-07-16 11:19:11 -07:00
2018-12-17 09:22:11 -08:00
## README
2018-09-19 10:24:31 -07:00
The [README.md ](./README.md ) is also the landing page for the documentation
2018-09-27 01:52:24 -07:00
on the website. During the Jenkins build, the current commit is added to the bottom
of the README.
2018-09-19 10:24:31 -07:00
2018-12-17 09:22:11 -08:00
## Config.js
2018-09-19 10:24:31 -07:00
2018-09-21 17:37:42 -07:00
The [config.js ](./.vuepress/config.js ) generates the sidebar and Table of Contents
2018-09-19 10:24:31 -07:00
on the website docs. Note the use of relative links and the omission of
file extensions. Additional features are available to improve the look
of the sidebar.
2018-12-17 09:22:11 -08:00
## Links
2018-09-19 10:24:31 -07:00
**NOTE:** Strongly consider the existing links - both within this directory
and to the website docs - when moving or deleting files.
Relative links should be used nearly everywhere, having discovered and weighed the following:
2018-12-17 09:22:11 -08:00
### Relative
2018-09-19 10:24:31 -07:00
Where is the other file, relative to the current one?
- works both on GitHub and for the VuePress build
- confusing / annoying to have things like: `../../../../myfile.md`
- requires more updates when files are re-shuffled
2018-12-17 09:22:11 -08:00
### Absolute
2018-09-19 10:24:31 -07:00
Where is the other file, given the root of the repo?
- works on GitHub, doesn't work for the VuePress build
- this is much nicer: `/docs/hereitis/myfile.md`
- if you move that file around, the links inside it are preserved (but not to it, of course)
2018-12-17 09:22:11 -08:00
### Full
2018-09-19 10:24:31 -07:00
The full GitHub URL to a file or directory. Used occasionally when it makes sense
to send users to the GitHub.
2018-12-17 09:22:11 -08:00
## Building Locally
2018-09-19 10:24:31 -07:00
2019-12-10 06:29:46 -08:00
Make sure you are in the `docs` directory and run the following commands:
2018-09-21 17:37:42 -07:00
2019-12-10 06:29:46 -08:00
```sh
rm -rf node_modules
2018-09-21 17:37:42 -07:00
```
2019-12-10 06:29:46 -08:00
This command will remove old version of the visual theme and required packages. This step is optional.
2018-09-21 17:37:42 -07:00
2019-12-10 06:29:46 -08:00
```sh
npm install
2018-09-21 17:37:42 -07:00
```
2019-12-10 06:29:46 -08:00
Install the theme and all dependencies.
2018-09-21 17:37:42 -07:00
2019-12-10 06:29:46 -08:00
```sh
npm run serve
2018-09-21 17:37:42 -07:00
```
2019-12-10 06:29:46 -08:00
Run `pre` and `post` hooks and start a hot-reloading web-server. See output of this command for the URL (it is often https://localhost:8080).
2018-09-21 17:37:42 -07:00
2019-12-10 06:29:46 -08:00
To build documentation as a static website run `npm run build` . You will find the website in `.vuepress/dist` directory.
2018-09-19 10:24:31 -07:00
2018-12-17 09:22:11 -08:00
## Build RPC Docs
2019-03-28 09:39:21 -07:00
First, run `make tools` from the root of repo, to install the swagger-ui tool.
2018-12-17 09:22:11 -08:00
2019-08-01 11:02:35 -07:00
Then, edit the `swagger.yaml` manually; it is found [here ](https://github.com/cosmos/cosmos-sdk/blob/master/client/lcd/swagger-ui/swagger.yaml )
2018-12-17 09:22:11 -08:00
Finally, run `make update_gaia_lite_docs` from the root of the repo.
## Search
We are using [Algolia ](https://www.algolia.com ) to power full-text search. This uses a public API search-only key in the `config.js` as well as a [cosmos_network.json ](https://github.com/algolia/docsearch-configs/blob/master/configs/cosmos_network.json ) configuration file that we can update with PRs.
## Consistency
2018-09-19 10:24:31 -07:00
Because the build processes are identical (as is the information contained herein), this file should be kept in sync as
2020-11-27 04:57:14 -08:00
much as possible with its [counterpart in the Tendermint Core repo ](https://github.com/tendermint/tendermint/blob/v0.34.0/docs/DOCS_README.md ).
2018-10-04 04:00:24 -07:00
2018-12-20 10:03:59 -08:00
### Update and Build the RPC docs
1. Execute the following command at the root directory to install the swagger-ui generate tool.
2019-09-03 05:27:23 -07:00
```bash
make tools
```
2018-12-20 10:03:59 -08:00
2. Edit API docs
2019-09-03 05:27:23 -07:00
1. Directly Edit API docs manually: `client/lcd/swagger-ui/swagger.yaml` .
2. Edit API docs within the [Swagger Editor ](https://editor.swagger.io/ ). Please refer to this [document ](https://swagger.io/docs/specification/2-0/basic-structure/ ) for the correct structure in `.yaml` .
2018-12-20 10:03:59 -08:00
3. Download `swagger.yaml` and replace the old `swagger.yaml` under fold `client/lcd/swagger-ui` .
4. Compile gaiacli
2019-09-03 05:27:23 -07:00
```bash
make install
```