forked from cosmos/cosmos-sdk
-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add documentation on documentation deployment (cosmos#13739)
- Loading branch information
1 parent
9b8e1a1
commit 0e421d8
Showing
5 changed files
with
108 additions
and
53 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,14 @@ | ||
| # CODEOWNERS: https://help.github.com/articles/about-codeowners/ | ||
|
|
||
| # NOTE: Order is important; the last matching pattern takes the | ||
| # most precedence. | ||
| # NOTE: Order is important; the last matching pattern takes the most precedence | ||
|
|
||
| # Primary repo maintainers | ||
|
|
||
| * @cosmos/sdk-core-dev | ||
|
|
||
| # CODEOWNERS for docs configuration | ||
|
|
||
| /docs/docusaurus.config.js @julienrbrt @tac0turtle | ||
| /docs/sidebars.js @julienrbrt @tac0turtle | ||
| /docs/pre.sh @julienrbrt @tac0turtle | ||
| /docs/post.sh @julienrbrt @tac0turtle |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,57 +1,79 @@ | ||
| # Updating the docs | ||
|
|
||
| If you want to open a PR in Cosmos SDK to update the documentation, please follow the guidelines in [`CONTRIBUTING.md`](https://github.com/cosmos/cosmos-sdk/tree/main/CONTRIBUTING.md#updating-documentation). | ||
| If you want to open a PR in Cosmos SDK to update the documentation, please follow the guidelines in [`CONTRIBUTING.md`](https://github.com/cosmos/cosmos-sdk/tree/main/CONTRIBUTING.md#updating-documentation) and the [Documentation Writing Guidelines](./DOC_WRITING_GUIDELINES.md). | ||
|
|
||
| ## Docs Build Workflow | ||
| ## Stack | ||
|
|
||
| The documentation for Cosmos SDK is hosted at https://docs.cosmos.network and built from the files in the `/docs` directory. | ||
| It is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. | ||
|
|
||
| ### How It Works | ||
|
|
||
| There is a GitHub Action listening for changes in the `/docs` directory for the `main` branch and each supported version branch (e.g. `release/v0.46.x`). Any updates to files in the `/docs` directory will automatically trigger a website deployment. Under the hood, the private website repository has a `make build-docs` target consumed by a Github Action within that repository. | ||
| It is built using the following stack: | ||
|
|
||
| ## README | ||
| * [Docusaurus 2](https://docusaurus.io) | ||
| * Vuepress (pre v0.47) | ||
| * [Algolia DocSearch](https://docsearch.algolia.com/) | ||
|
|
||
| The [README.md](./README.md) is both the README for the repository and the configuration for the layout of the landing page. | ||
| ```js | ||
| algolia: { | ||
| appId: "QLS2QSP47E", | ||
| apiKey: "067b84458bfa80c295e1d4f12c461911", | ||
| indexName: "cosmos_network", | ||
| contextualSearch: false, | ||
| }, | ||
| ``` | ||
|
|
||
| ## Links | ||
| * GitHub Pages | ||
|
|
||
| **NOTE:** Strongly consider the existing links - both within this directory | ||
| and to the website docs - when moving or deleting files. | ||
| ## Docs Build Workflow | ||
|
|
||
| Relative links should be used nearly everywhere, due to versionning. | ||
| Note that in case of page reshufling, you must update all links references. | ||
| The docs are built and deployed automatically on GitHub Pages by a [GitHub Action workflow](../.github/workflows/deploy-docs.yml). | ||
| The workflow is triggered on every push to the `main` and `release/v**` branches, every time documentations or specs are modified. | ||
|
|
||
| ### Full | ||
| ### How It Works | ||
|
|
||
| The full GitHub URL to a file or directory. Used occasionally when it makes sense | ||
| to send users to the GitHub. | ||
| There is a GitHub Action listening for changes in the `/docs` directory for the `main` branch and each supported version branch (e.g. `release/v0.46.x`). Any updates to files in the `/docs` directory will automatically trigger a website deployment. Under the hood, the private website repository has a `make build-docs` target consumed by a Github Action within that repository. | ||
|
|
||
| ## Building Locally | ||
| ## How to Build the Docs Locally | ||
|
|
||
| Make sure you are in the `docs` directory and run the following commands: | ||
| Go to the `docs` directory and run the following commands: | ||
|
|
||
| ```shell | ||
| rm -rf node_modules | ||
| cd docs | ||
| npm install | ||
| ``` | ||
|
|
||
| This command will remove old version of the visual theme and required packages. This step is optional. | ||
| For starting only the current documentation, run: | ||
|
|
||
| ```shell | ||
| npm install | ||
| npm start | ||
| ``` | ||
|
|
||
| Install the theme and all dependencies. | ||
| It runs `pre.sh` scripts to get all the docs that are not already in the `docs/docs` folder. | ||
| It also runs `post.sh` scripts to clean up the docs and remove unnecessary files when quitting. | ||
|
|
||
| Note, the command above only build the docs for the current versions. | ||
| With the drawback that none of the redirections works. So, you'll need to go to /main to see the docs. | ||
|
|
||
| To build all the docs (including versioned documentation), run: | ||
|
|
||
| ```shell | ||
| npm start | ||
| make build-docs | ||
| ``` | ||
|
|
||
| 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:3000). | ||
| ## What to for new major SDK versions | ||
|
|
||
| When a new major version of the SDK is released, the following steps should be taken: | ||
|
|
||
| * On the `release/vX.Y.Z` branch, remove the deploy action (`.github/workflows/deploy-docs.yml`), for avoiding deploying the docs from the release branches | ||
| * Each time a new version is released (on docusaurus), drop support from the oldest versions. | ||
| * If the old version is still running vuepress (v0.45, v0.46), remove its line from `vuepress_versions` | ||
| * If any, remove the outdated redirections from `docusaurus.config.js` and add the base version redirection (`/vX.XX`) to `/main`. | ||
|
|
||
| To build documentation as a static website run `npm run build`. | ||
| ```js | ||
| { | ||
| from: ["/", "/master", "/v0.43", "/v0.44", "/v0.XX"], // here add the deprecated version | ||
| to: "/main", | ||
| }, | ||
| ``` | ||
|
|
||
| ## Search | ||
| * Add the new version sidebar to the list of versionned sidebar and add the version to `versions` | ||
|
|
||
| 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. | ||
| Learn more about [versioning](https://docusaurus.io/docs/versioning) in Docusaurus. |