Skip to content

Conversation

dannywillems
Copy link
Member

@dannywillems dannywillems commented Oct 2, 2025

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:
image

Copy link

@Copilot Copilot AI left a 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

@dannywillems dannywillems force-pushed the dw/add-documentation-guidelines branch 2 times, most recently from 5a089d3 to 21c3d10 Compare October 2, 2025 14:24
@dannywillems dannywillems moved this to Done in Rust node Oct 2, 2025
@dannywillems dannywillems force-pushed the dw/add-documentation-guidelines branch 2 times, most recently from 9618e1e to ae10618 Compare October 2, 2025 14:32
@dannywillems dannywillems linked an issue Oct 2, 2025 that may be closed by this pull request
6 tasks
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}"
Copy link
Collaborator

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?

Copy link
Collaborator

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?

Copy link
Member Author

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).

Copy link
Member Author

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
Copy link
Collaborator

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 🙏

Copy link
Member Author

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
Copy link
Collaborator

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

Copy link
Member Author

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.

@dannywillems dannywillems force-pushed the dw/add-documentation-guidelines branch from ae10618 to 1e331ad Compare October 2, 2025 18:01
@dannywillems dannywillems merged commit fd5aeee into develop Oct 3, 2025
59 of 61 checks passed
@dannywillems dannywillems deleted the dw/add-documentation-guidelines branch October 16, 2025 11:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

[Ledger App] Provide test vectors for signing zkApp

2 participants