From bd9cad82aa865d2db69f091ebb083259f4fd42e5 Mon Sep 17 00:00:00 2001 From: Dominique Date: Wed, 20 Nov 2024 14:29:35 +0100 Subject: [PATCH] docs: update docs & benchmarks related docs (#1553) * docs: update docs & benchmarks related docs * updated the contributor s page --- README.md | 2 ++ RELEASE.md | 2 +- benchmarks/README.md | 6 +++++- docs/README.md | 4 ++-- guides/CONTRIBUTING.md | 3 +-- 5 files changed, 11 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 1491405a4..dcbc2e815 100644 --- a/README.md +++ b/README.md @@ -411,3 +411,5 @@ Intel Cascade Lake Hard-Disk: 500GB ``` + +Benchmarks are automatically published in Github pages under the url https://paritytech.github.io/substrate-api-sidecar/dev/bench/. The data in the graphs are updated with every new commit/push in the `master` branch (refer to the [benchmark.yml](https://github.com/paritytech/substrate-api-sidecar/blob/master/.github/workflows/benchmark.yml) for more details). diff --git a/RELEASE.md b/RELEASE.md index b5f72c65d..b3f0a69bc 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -42,7 +42,7 @@ _Estimated Time Needed: Depending on your machine and the syncing mode you choos 1. Update the version in the package.json (this is very important for releasing on NPM). -1. Update the substrate-api-sidecar version in the docs by going into `docs/src/openapi-v1.yaml`, and changing the `version` field under `info` to the releases respected version. Then run `yarn build:docs`. +1. Update the substrate-api-sidecar version in the docs by going into `docs/src/openapi-v1.yaml`, and changing the `version` field under `info` to the releases respected version. No need to run `yarn build:docs` (refer to the [README](./docs/README) for more info) Note: you can double check that the version is updated by opening the page `index.html` (from folder `docs/dist`) on your browser. The version badge is located on the top of the page next to the title. diff --git a/benchmarks/README.md b/benchmarks/README.md index 2586d387d..839f7b86f 100644 --- a/benchmarks/README.md +++ b/benchmarks/README.md @@ -111,4 +111,8 @@ ex3: ``` $ yarn $ yarn bench --log-level=info --time=30s --endpoint=/accounts/{accountId}/balance-info -``` \ No newline at end of file +``` + +### Benchmarks Published + +Benchmarks are automatically published in Github pages under the url https://paritytech.github.io/substrate-api-sidecar/dev/bench/. The data in the graphs are updated with every new commit/push in the `master` branch (refer to the [benchmark.yml](https://github.com/paritytech/substrate-api-sidecar/blob/master/.github/workflows/benchmark.yml) for more details). \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index cf0ff3500..c6df6a21d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,6 @@ OpenApi spec for [substrate-api-sidecar](https://github.com/paritytech/substrate If you add a new endpoint or update an existing one (by modifying its parameters or output), you will also need to update the documentation (OpenApi specs). Here are some common steps to follow in order to do that: - Update this [file](https://github.com/paritytech/substrate-api-sidecar/blob/master/docs/src/openapi-v1.yaml) by adding or updating the corresponding endpoint description in the `paths` and `schemas` sections. - After you complete the changes, verify that the `yaml` file has no errors by copying the contents of this [file](https://github.com/paritytech/substrate-api-sidecar/blob/master/docs/src/openapi-v1.yaml) into the [Swagger Editor](https://editor.swagger.io/) or the [New Swagger Editor](https://editor-next.swagger.io/). -- If there are no errors, run `yarn build:docs` from the root directory of this repository. This will make sure that the `dist` is updated with the current changes. -- Next, open the `docs/dist/index.html` page (by copying its path) in your browser to confirm that all changes have been applied and appear as expected. - If everything looks good, push the changes. +- To preview the docs locally, you can run `yarn build:docs` from the root directory of this repository. This will update the `docs/dist/index.html` page which you can open (by copying its path) in your browser and verify that the content appear as expected. Please do not push/commit this file (or the `dist` folder) in your PR since this is not necessary. The docs will be build and published automatically in Github pages from the workflow ([docs.yml](https://github.com/paritytech/substrate-api-sidecar/blob/master/.github/workflows/docs.yml)). + diff --git a/guides/CONTRIBUTING.md b/guides/CONTRIBUTING.md index 7a0dd91c4..3d2b759ae 100644 --- a/guides/CONTRIBUTING.md +++ b/guides/CONTRIBUTING.md @@ -23,9 +23,8 @@ where reviewers will be able to review your changes made. - If you add a new endpoint or update an existing one (by modifying its parameters or output), you will also need to update the documentation (OpenApi specs). Here are some common steps to follow in order to do that: - Update this [file](https://github.com/paritytech/substrate-api-sidecar/blob/master/docs/src/openapi-v1.yaml) by adding or updating the corresponding endpoint description in the `paths` and `schemas` sections. - After you complete the changes, verify that the `yaml` file has no errors by copying the contents of this [file](https://github.com/paritytech/substrate-api-sidecar/blob/master/docs/src/openapi-v1.yaml) into the [Swagger Editor](https://editor.swagger.io/) or the [New Swagger Editor](https://editor-next.swagger.io/). - - If there are no errors, run `yarn build:docs` from the root directory of this repository. This will make sure that the `dist` is updated with the current changes. - - Next, open the `docs/dist/index.html` page (by copying its path) in your browser to confirm that all changes have been applied and appear as expected. - If everything looks good, push the changes. + - To preview the docs locally, you can run `yarn build:docs` from the root directory of this repository. This will update the `docs/dist/index.html` page which you can open (by copying its path) in your browser and verify that the content appear as expected. Please do not push/commit this file (or the `dist` folder) in your PR since this is not necessary. The docs will be build and published automatically in Github pages from the workflow ([docs.yml](https://github.com/paritytech/substrate-api-sidecar/blob/master/.github/workflows/docs.yml)). ## Rules