github.com/fibonacci-chain/fbc@v0.0.0-20231124064014-c7636198c1e9/libs/cosmos-sdk/docs/DOCS_README.md (about)

     1  # Updating the docs
     2  
     3  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)
     4  
     5  ## Translating
     6  
     7  - 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, ...).
     8  - Always translate content living on `master`. 
     9  - 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/`.
    10  - Specify the release/tag of the translation in the README of your translation folder. Update the release/tag each time you update the translation.
    11  
    12  ## Docs Build Workflow
    13  
    14  The documentation for the Cosmos SDK is hosted at https://cosmos.network/docs/
    15  
    16  built from the files in this (`/docs`) directory for
    17  [master](https://github.com/cosmos/cosmos-sdk/tree/master/docs).
    18  
    19  ### How It Works
    20  
    21  There is a CircleCI job listening for changes in the `/docs` directory, on
    22  the `master` branch. Any updates to files in this directory
    23  on that branch will automatically trigger a website deployment. Under the hood,
    24  the private website repository has a `make build-docs` target consumed by a CircleCI job in that repo.
    25  
    26  ## README
    27  
    28  The [README.md](./README.md) is also the landing page for the documentation
    29  on the website. During the Jenkins build, the current commit is added to the bottom
    30  of the README.
    31  
    32  ## Config.js
    33  
    34  The [config.js](./.vuepress/config.js) generates the sidebar and Table of Contents
    35  on the website docs. Note the use of relative links and the omission of
    36  file extensions. Additional features are available to improve the look
    37  of the sidebar.
    38  
    39  ## Links
    40  
    41  **NOTE:** Strongly consider the existing links - both within this directory
    42  and to the website docs - when moving or deleting files.
    43  
    44  Relative links should be used nearly everywhere, having discovered and weighed the following:
    45  
    46  ### Relative
    47  
    48  Where is the other file, relative to the current one?
    49  
    50  - works both on GitHub and for the VuePress build
    51  - confusing / annoying to have things like: `../../../../myfile.md`
    52  - requires more updates when files are re-shuffled
    53  
    54  ### Absolute
    55  
    56  Where is the other file, given the root of the repo?
    57  
    58  - works on GitHub, doesn't work for the VuePress build
    59  - this is much nicer: `/docs/hereitis/myfile.md`
    60  - if you move that file around, the links inside it are preserved (but not to it, of course)
    61  
    62  ### Full
    63  
    64  The full GitHub URL to a file or directory. Used occasionally when it makes sense
    65  to send users to the GitHub.
    66  
    67  ## Building Locally
    68  
    69  Make sure you are in the `docs` directory and run the following commands:
    70  
    71  ```sh
    72  rm -rf node_modules
    73  ```
    74  
    75  This command will remove old version of the visual theme and required packages. This step is optional.
    76  
    77  ```sh
    78  npm install
    79  ```
    80  
    81  Install the theme and all dependencies.
    82  
    83  ```sh
    84  npm run serve
    85  ```
    86  
    87  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).
    88  
    89  To build documentation as a static website run `npm run build`. You will find the website in `.vuepress/dist` directory.
    90  
    91  ## Build RPC Docs
    92  
    93  First, run `make tools` from the root of repo, to install the swagger-ui tool.
    94  
    95  Then, edit the `swagger.yaml` manually; it is found [here](https://github.com/cosmos/cosmos-sdk/blob/master/client/lcd/swagger-ui/swagger.yaml)
    96  
    97  Finally, run `make update_gaia_lite_docs` from the root of the repo.
    98  
    99  ## Search
   100  
   101  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.
   102  
   103  ## Consistency
   104  
   105  Because the build processes are identical (as is the information contained herein), this file should be kept in sync as
   106  much as possible with its [counterpart in the Tendermint Core repo](https://github.com/tendermint/tendermint/blob/master/docs/DOCS_README.md).
   107  
   108  ### Update and Build the RPC docs
   109  
   110  1. Execute the following command at the root directory to install the swagger-ui generate tool.
   111     ```bash
   112     make tools
   113     ```
   114  2. Edit API docs
   115     1. Directly Edit API docs manually: `client/lcd/swagger-ui/swagger.yaml`.
   116     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`.
   117  3. Download `swagger.yaml` and replace the old `swagger.yaml` under fold `client/lcd/swagger-ui`.
   118  4. Compile gaiacli
   119     ```bash
   120     make install
   121     ```