Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add documentation contribution instructions #6294

Merged
merged 6 commits into from
Jan 18, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,20 @@ Run script to download dashboards to `./dashboards` folder
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. 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`
Copy link
Member

@nflaig nflaig Jan 17, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to clarify yarn docs:build just builds part of the docs, namely the CLI references, if there are no updates to those I don't think this step is required. It also copies some files over to docs dir, so has to be run at least once. Might be fine how we documented it here though.

yarn docs:serve will watch for changes and hot reload the UI

Copy link
Contributor

@ensi321 ensi321 Jan 17, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be fine how we documented it here though.

Yea I agree. Just high level description here in CONTRIBUTING.md. For details of command usage, contributors will need to look deeper.

Copy link
Member

@matthewkeil matthewkeil Jan 17, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nflaig I think its a nice to have for those that do not know there are generated sections. Perhaps a comment that it only needs to be run once but having it noted seems important to me.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's always better to include too much than too little, even if one step is not always required, executing it won't hurt, it'll just be redundant, but it covers all cases if they just do it every time.


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:

```sh
yarn clean && yarn clean:nm && yarn && yarn build
```

philknows marked this conversation as resolved.
Show resolved Hide resolved
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

Issues and pull requests are subject to the following labeling guidelines.
Expand Down
Loading