From 89e49f5112296ebcd2d2ea70775832e23f3c6499 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Sun, 14 Jan 2024 14:53:47 -0500 Subject: [PATCH 1/6] add documentation contribution instructions --- CONTRIBUTING.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b5990d2eabbf..7d23712201b4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -229,6 +229,25 @@ Run script to download dashboards to `./dashboards` folder node scripts/download_dashboards.mjs ``` +## Contributing to Documentation + +When submitting PRs for documentation updates, build the docs locally and ensure functionality before submission. To build docs locally, ensure you have Python installed, then follow these steps: + +```sh +pip install -r docs/requirements.txt +yarn build:docs +cd docs +mkdocs serve --watch pages +``` + +Your locally served docs will then be accessible at http://localhost:8000. + +If you run into build issues due to circular dependencies, branch switching or other incompatibilities, try cleaning your modules and rebuild your dependencies with: + +``` +yarn clean && yarn clean:nm && yarn && yarn build +``` + ## Label Guide Issues and pull requests are subject to the following labeling guidelines. From df0f9b21ad45440851ce5ac11a78f32c36c467a2 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Mon, 15 Jan 2024 21:23:26 -0500 Subject: [PATCH 2/6] docs contribution to include cmd and wordlist --- CONTRIBUTING.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7d23712201b4..590ac87c26e8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -231,23 +231,18 @@ node scripts/download_dashboards.mjs ## Contributing to Documentation -When submitting PRs for documentation updates, build the docs locally and ensure functionality before submission. To build docs locally, ensure you have Python installed, then follow these steps: - -```sh -pip install -r docs/requirements.txt -yarn build:docs -cd docs -mkdocs serve --watch pages -``` +When submitting PRs for documentation updates, build and run the docs locally to ensure functionality before submission. To build the docs locally, ensure you have Python installed, then simply execute `yarn build:docs` Your locally served docs will then be accessible at http://localhost:8000. If you run into build issues due to circular dependencies, branch switching or other incompatibilities, try cleaning your modules and rebuild your dependencies with: -``` +```sh yarn clean && yarn clean:nm && yarn && yarn build ``` +We also use a spelling [wordlist](https://github.com/ChainSafe/lodestar/blob/unstable/.wordlist.txt) as part of our documentation checks. If using unrecognized words or abbreviations, please extend the wordlist to pass checks. Make sure the list is sorted with `./scripts/wordlist_sort.sh`. + ## Label Guide Issues and pull requests are subject to the following labeling guidelines. From 3bce7d9c8c46d2f18cf470c522ef866aa1e5b6db Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Mon, 15 Jan 2024 21:32:52 -0500 Subject: [PATCH 3/6] spell check documentation --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 590ac87c26e8..2e79ae562805 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -231,9 +231,9 @@ node scripts/download_dashboards.mjs ## Contributing to Documentation -When submitting PRs for documentation updates, build and run the docs locally to ensure functionality before submission. To build the docs locally, ensure you have Python installed, then simply execute `yarn build:docs` +When submitting PRs for documentation updates, build and run the documentation locally to ensure functionality before submission. To build the documentation locally, ensure you have Python installed, then simply execute `yarn build:docs` -Your locally served docs will then be accessible at http://localhost:8000. +Your locally served documentation will then be accessible at http://localhost:8000. If you run into build issues due to circular dependencies, branch switching or other incompatibilities, try cleaning your modules and rebuild your dependencies with: From 9c08da26d7440256218266abdcb66586a2626af8 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Mon, 15 Jan 2024 21:36:07 -0500 Subject: [PATCH 4/6] add wordlist check script --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2e79ae562805..10df202d466b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -241,7 +241,7 @@ If you run into build issues due to circular dependencies, branch switching or o yarn clean && yarn clean:nm && yarn && yarn build ``` -We also use a spelling [wordlist](https://github.com/ChainSafe/lodestar/blob/unstable/.wordlist.txt) as part of our documentation checks. If using unrecognized words or abbreviations, please extend the wordlist to pass checks. Make sure the list is sorted with `./scripts/wordlist_sort.sh`. +We also use a spelling [wordlist](https://github.com/ChainSafe/lodestar/blob/unstable/.wordlist.txt) as part of our documentation checks. If using unrecognized words or abbreviations, please extend the wordlist to pass checks. Make sure the list is sorted with `./scripts/wordlist_sort.sh` and checked with `./scripts/wordlist_sort_check.sh` for sorting and duplicates. ## Label Guide From 61aec3b214b14150a237067e0830fc9bf0a0813b Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Mon, 15 Jan 2024 21:52:20 -0500 Subject: [PATCH 5/6] word list correction --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 10df202d466b..74a5edee9877 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -241,7 +241,7 @@ If you run into build issues due to circular dependencies, branch switching or o yarn clean && yarn clean:nm && yarn && yarn build ``` -We also use a spelling [wordlist](https://github.com/ChainSafe/lodestar/blob/unstable/.wordlist.txt) as part of our documentation checks. If using unrecognized words or abbreviations, please extend the wordlist to pass checks. Make sure the list is sorted with `./scripts/wordlist_sort.sh` and checked with `./scripts/wordlist_sort_check.sh` for sorting and duplicates. +We also use a spelling [word list](https://github.com/ChainSafe/lodestar/blob/unstable/.wordlist.txt) as part of our documentation checks. If using unrecognized words or abbreviations, please extend the wordlist to pass checks. Make sure the list is sorted with `./scripts/wordlist_sort.sh` and checked with `./scripts/wordlist_sort_check.sh` for sorting and duplicates. ## Label Guide From dfc7be620f41ec7e8fa0b62a9b31350571f0e8a0 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Tue, 16 Jan 2024 14:25:21 -0500 Subject: [PATCH 6/6] incorporate feedback --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 74a5edee9877..fbc23571aa37 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -231,7 +231,7 @@ node scripts/download_dashboards.mjs ## Contributing to Documentation -When submitting PRs for documentation updates, build and run the documentation locally to ensure functionality before submission. To build the documentation locally, ensure you have Python installed, then simply execute `yarn build:docs` +When submitting PRs for documentation updates, build and run the documentation locally to ensure functionality before submission. For first time documentation contributors, install the python dependencies with `yarn docs:install`. Build the documentation locally with `yarn docs:build` and serve with `yarn docs:serve` Your locally served documentation will then be accessible at http://localhost:8000. @@ -241,7 +241,7 @@ If you run into build issues due to circular dependencies, branch switching or o yarn clean && yarn clean:nm && yarn && yarn build ``` -We also use a spelling [word list](https://github.com/ChainSafe/lodestar/blob/unstable/.wordlist.txt) as part of our documentation checks. If using unrecognized words or abbreviations, please extend the wordlist to pass checks. Make sure the list is sorted with `./scripts/wordlist_sort.sh` and checked with `./scripts/wordlist_sort_check.sh` for sorting and duplicates. +We also use a spelling [word list](https://github.com/ChainSafe/lodestar/blob/unstable/.wordlist.txt) as part of our documentation checks. If using unrecognized words or abbreviations, please extend the word list to pass checks. Make sure the list is sorted with `./scripts/wordlist_sort.sh` and checked with `./scripts/wordlist_sort_check.sh` for sorting and duplicates. ## Label Guide