-
Notifications
You must be signed in to change notification settings - Fork 40
Website: add documentation guidelines + code ref in doc #1493
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
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Pull Request Overview
This PR adds comprehensive documentation guidelines for the Mina Rust project, establishing a system for referencing code snippets directly from the codebase in documentation. The implementation includes a new documentation page, automated verification of code references, and configuration for the Docusaurus GitHub codeblock plugin.
Key changes:
- Introduces documentation guidelines with code reference patterns
- Adds automated CI verification to ensure code references remain valid
- Configures Docusaurus plugin for fetching code from GitHub
Reviewed Changes
Copilot reviewed 6 out of 7 changed files in this pull request and generated no comments.
Show a summary per file
File | Description |
---|---|
website/docs/developers/documentation-guidelines.md | New documentation page explaining code reference patterns and best practices |
website/sidebars.ts | Adds Documentation section to developer navigation |
website/package.json | Adds docusaurus-theme-github-codeblock dependency |
website/docusaurus.config.ts | Configures GitHub codeblock theme |
.github/workflows/docs.yaml | Integrates code reference verification into CI pipeline |
.github/scripts/verify-code-references.sh | New bash script for validating code references against actual source code |
Files not reviewed (1)
- website/package-lock.json: Language not supported
5a089d3
to
21c3d10
Compare
9618e1e
to
ae10618
Compare
source_file="${REPO_ROOT}/${file_path}" | ||
if [[ ! -f "$source_file" ]]; then | ||
echo -e "${RED}✗${NC} Invalid reference in ${doc_file}:${line_num}" | ||
echo " File not found: ${file_path}" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does this case cover the file existing but not having permissions?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And by the way, this works only for the related repo? As in, our doc website will. check only references from the rust node repo or can it check any arbitrary repository as long as you configure it?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does this case cover the file existing but not having permissions?
-f filename
checks if the file exists. We should not care about the permissions as it would be on code that is supposed to have at least the read
permissions (code, toml, yaml, etc).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And by the way, this works only for the related repo? As in, our doc website will. check only references from the rust node repo or can it check any arbitrary repository as long as you configure it?
Yes, only related repo for now. I will think about something else for other repositories. We will need to add something for the Caml repo for instance.
# Documentation Guidelines | ||
|
||
This guide explains how to write and maintain documentation for the Mina Rust | ||
project, including how to reference code from the codebase. Referencing code |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
as always, check the line breaks 🙏
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The line breaks at 80 characters, and it is fine as in markdown, it adds a new line only when you have two new lines.
`\n` -> no new line when rendered
`\n\n` -> a new line when rendered
If code is added or removed and line numbers shift: | ||
|
||
1. The verification script will detect the mismatch in CI | ||
2. Update the `CODE_REFERENCE` comment with new line numbers |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's not clear from reading this if this happens automatically or not. My understanding is that NOT, but could be a bit clearer
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It does not happen automatically. It is manual.
ae10618
to
1e331ad
Compare
In the future, we can add a tab with the OCaml code on one side, and the Rust code on the other side.
Here is an example of the output when using the plugin:
