diff --git a/.github/styles/config/vocabularies/Technical/accept.txt b/.github/styles/config/vocabularies/Technical/accept.txt new file mode 100644 index 00000000..7812612a --- /dev/null +++ b/.github/styles/config/vocabularies/Technical/accept.txt @@ -0,0 +1,190 @@ +# Technical terms for iExec documentation + +# Function Names +protectData +grantAccess +revokeAllAccess +revokeOneAccess +transferOwnership +createCollection +removeCollection +removeProtectedDataFromCollection +sendEmail +sendTelegram +getValue +deserializer +deserialize +consumeProtectedData +rentProtectedData +subscribeToCollection +buyProtectedData +setProtectedDataForSale +setProtectedDataToRenting +setProtectedDataToSubscription +setProtectedDataRentingParams +setSubscriptionParams +addToCollection +removeProtectedDataFromCollection +removeProtectedDataFromRenting +removeProtectedDataForSale +addAppToAddOnlyAppWhitelist +createAddOnlyAppWhitelist +getUserAddOnlyAppWhitelist +getGrantedAccess +getProtectedData +getResultFromCompletedTask +getCollectionOwners +getCollectionsByOwner +getCollectionSubscriptions +getProtectedDataInCollections +getProtectedDataPricingParams +getRentals +fetchMyContacts +fetchUserContacts +unpublish + +# Function Parameters +authorizedApp +authorizedUser +grantedAccess +collectionId +appsWhitelist +userWhitelist +useVoucher +voucherAddress +voucherOwner +subscriberAddress +renterAddress +apporder +datasetorder +workerpoolorder +requestorder +requesters +workerpools +apporders +appmaxprice +datasetmaxprice +workerpoolmaxprice +apprestrict +requesterrestrict +workerpoolrestrict +datasetprice +taskId +dealId +userAddress +resultHash +resultSeal +enclaveSign +workerpoolSign +inputFiles +zipFile +encryptionKey +multiaddr +ipfsNode +ipfsGateway +emailSubject +emailContent +contentType +senderName +telegramContent +//TODO: check +param +params +args +environnement +pageSize +subgraphUrl +subgraph +iexecOptions +uploadMode +allowDebug +requiredSchema +keypair +collectionOwner +isRentable +isDistributed +NFTs +creationTimestamp +transactionHash +txHash +boolean +bigint +newOwner +maxPrice +workerpoolorders + +# iExec/Web3 Terms +iExec +CPUs +LLMs +Agentic +DApp +DApps +blockchain +ethereum +intel +nano +workerpool +protectedData +dataProtector +iApp +sconification +middleware +oracle +MREnclave +Gramine +//TODO: check +permissioning +Permissioning +arithmetics +webservers +Javascript +Dockerizable +Dockerize +Dockerhub +dockerized +keystore +Webpack +json +polyfills +Buildx +hardcoding +npm +Arweave +cryptocurrency +cryptocurrencies +crypto +onchain +offchain +//TODO: check +mainchain +Sidechain +Bellecour +Mainnet +Testnet +Metamask +Binance +Coinbase +Uniswap +Szabo +presale +presigned +untrusted +dev +cryptocurrecny +Unmatching +incentivized +Whitepaper +deserialization +enclaveChallenge +Borsh +Arbitrum +Stargate +Github +subgraphs +hackathons +tokenization +chipset +auditable +Composable +Activable diff --git a/.github/styles/config/vocabularies/Technical/reject.txt b/.github/styles/config/vocabularies/Technical/reject.txt new file mode 100644 index 00000000..79c07ea1 --- /dev/null +++ b/.github/styles/config/vocabularies/Technical/reject.txt @@ -0,0 +1,2 @@ +# Terms to reject - currently empty +# Add terms here that should always be flagged as errors diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 00000000..077a8f96 --- /dev/null +++ b/.github/workflows/vale.yml @@ -0,0 +1,27 @@ +name: Documentation Quality + +on: + pull_request: + +jobs: + vale: + name: Vale Documentation Quality Check + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run Vale + # Vale runs spell checking and basic grammar validation + # - reporter: github-pr-check provides concise feedback in PR comments + # - fail_on_error: false prevents workflow failures on minor issues + # - filter_mode: added only checks files changed in the PR + # - vale_flags: sets minimum alert level to suggestions only + uses: errata-ai/vale-action@v2.1.1 + with: + files: src/ + reporter: github-pr-check + fail_on_error: false + filter_mode: added + vale_flags: '--minAlertLevel=suggestion' diff --git a/.gitignore b/.gitignore index 7b041670..a8039465 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,8 @@ components.d.ts #mac .DS_Store + +#vale +.github/styles/* +!.github/styles/config/vocabularies/ +vale-report.txt diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 00000000..d8034b30 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,13 @@ +StylesPath = .github/styles +MinAlertLevel = suggestion +Packages = Google + +# Define the Technical vocabulary for custom terminology +Vocab = Technical + +[formats] +md = markdown + +[*.md] +BasedOnStyles = Vale, Google +IgnorePatterns = README.md diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index 3ab0ea49..cf83a599 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -110,23 +110,23 @@ export function getSidebar() { link: '/get-started/protocol/proof-of-contribution', }, { - text: '💸 Pay Per Task Model', + text: 'Pay Per Task Model', link: '/get-started/protocol/pay-per-task', }, { - text: 'iExec DOracle', - link: '/get-started/protocol/iexec-doracle', + text: 'Oracle', + link: '/get-started/protocol/oracle', }, { - text: '⚙️ Workers & Workerpools', + text: 'Workers & Workerpools', collapsed: true, items: [ { - text: '🚀 Worker Quick Start', + text: 'Worker Quick Start', link: '/get-started/protocol/worker/quick-start', }, { - text: '🔒 Manage Workerpool Access', + text: 'Manage Workerpool Access', link: '/get-started/protocol/worker/manage-access', }, ], diff --git a/README.md b/README.md index 0db0079a..5c8b2bfd 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,66 @@ - **Node.js**: Version 22 or higher - **npm**: Comes bundled with Node.js +- **Vale** (optional): For documentation linting and quality checks ## ⚙️ Configuration +### Documentation Quality with Vale + +We use [Vale](https://vale.sh/) to maintain high-quality documentation +standards. Vale checks your writing for clarity, consistency, and adherence to +our style guidelines, helping us maintain a coherent tone of voice, accurate +terminology, and overall editorial quality across the project. + +#### Installing Vale + +**macOS:** + +```bash +brew install Vale/tap/vale +``` + +**Linux (Snap):** + +```bash +snap install vale +``` + +**Windows:** + +```bash +choco install vale +``` + +#### Running Vale Locally + +```bash +# Download and install external configuration sources +vale sync + +# Check all documentation files +vale src/ + +# Check specific files +vale src/get-started/helloWorld/1-overview.md + +# Get detailed output +vale --output=line src/ + +# Generate comprehensive report with statistics +vale --output=line src/ > vale-report.txt 2>&1 +``` + +#### Vale Rules + +Our Vale configuration uses the Google & Vale writing style guide, which helps +ensure: + +- Clear and concise language +- Consistent terminology +- Professional tone +- Accessibility best practices + ### Environment Variables (Optional) Some features of the application require environment variables. This @@ -138,6 +195,8 @@ Fork this repository and ensure you're working on the `main` branch: > you're satisfied with the preview > - All pull requests are reviewed by our team before being merged > - Feel free to ask questions in the pull request if you need clarification +> - **Documentation Quality**: Vale will automatically check your documentation +> for style and clarity ### Some conventions @@ -191,5 +250,4 @@ for input parameters: - Give recap of Workerpool address fo chains - Talk about ENS on Bellecour(it's not supported on arbitrum) - Rework Advanced iApp building guides. (from "old" protocol doc) -- Rework src\get-started\protocol\iexec-doracle.md (transfer to guide or - rewrite) +- Rework src\get-started\protocol\oracle.md (transfer to guide or rewrite) diff --git a/src/get-started/helloWorld.md b/src/get-started/helloWorld.md index fa23f2e5..c7311d74 100644 --- a/src/get-started/helloWorld.md +++ b/src/get-started/helloWorld.md @@ -2,7 +2,7 @@ title: Hello World Tutorial description: Kickstart your Web3 journey with iExec. In just 30 minutes, learn how to build - privacy-focused dApps, protect sensitive data, and manage data access. + privacy-focused DApp, protect sensitive data, and manage data access. ---