2018-12-17 09:22:11 -08:00
# Updating the docs
2018-11-14 11:44:17 -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 )
## Docs Build Workflow
2018-07-16 11:19:11 -07:00
2018-09-19 10:24:31 -07:00
The documentation for the Cosmos SDK is hosted at:
2018-07-16 11:19:11 -07:00
2018-09-19 10:24:31 -07:00
- https://cosmos.network/docs/ and
- https://cosmos-staging.interblock.io/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
[master ](https://github.com/cosmos/cosmos-sdk/tree/master/docs )
and [develop ](https://github.com/cosmos/cosmos-sdk/tree/develop/docs ),
respectively.
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
2018-12-17 09:22:11 -08:00
There is a CircleCI job listening for changes in the `/docs` directory, on both
2018-09-19 10:24:31 -07:00
the `master` and `develop` branches. Any updates to files in this directory
on those branches 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
2018-09-21 17:37:42 -07:00
To build and serve the documentation locally, run:
2019-01-08 08:13:04 -08:00
```bash
2018-09-21 17:37:42 -07:00
npm install -g vuepress
```
then change the following line in the `config.js` :
2019-01-08 08:13:04 -08:00
```js
2018-09-21 17:37:42 -07:00
base: "/docs/",
```
to:
2019-01-08 08:13:04 -08:00
```js
2018-09-21 17:37:42 -07:00
base: "/",
```
Finally, go up one directory to the root of the repo and run:
2019-01-08 08:13:04 -08:00
```bash
2018-09-21 17:37:42 -07:00
# from root of repo
vuepress build docs
cd dist/docs
python -m SimpleHTTPServer 8080
```
then navigate to localhost:8080 in your browser.
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
Then, edit the `swagger.yaml` manually; it is found [here ](https://github.com/cosmos/cosmos-sdk/blob/develop/client/lcd/swagger-ui/swagger.yaml )
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
much as possible with its [counterpart in the Tendermint Core repo ](https://github.com/tendermint/tendermint/blob/develop/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-01-08 08:13:04 -08:00
```bash
2018-12-20 10:03:59 -08:00
make tools
```
2. Edit API docs
1. Directly Edit API docs manually: `client/lcd/swagger-ui/swagger.yaml` .
2019-01-08 08:13:04 -08:00
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-01-08 08:13:04 -08:00
```bash
2018-12-20 10:03:59 -08:00
make install
```