diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c56aad8395..436b6fb303 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -63,3 +63,19 @@ repos: additional_dependencies: - packaging==26.0 args: [--verbose] + +# Vale prose linting for documentation. All styles are tracked in +# .vale/styles (no remote packages, so no `vale sync` needed). Vale needs +# docutils (rst2html) on PATH to lint reStructuredText, so both are +# installed into one isolated hook environment via the `vale` PyPI package +# (which bundles the official binary). +- repo: local + hooks: + - id: vale + name: vale + language: python + additional_dependencies: ['vale==3.13.0.0', 'docutils>=0.21'] + entry: vale + args: [--output=line, --minAlertLevel=error] + types: [rst] + files: ^docs/ diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000000..1ede5e8600 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,15 @@ +StylesPath = .vale/styles +MinAlertLevel = suggestion + +Vocab = NVIDIA + +[*.rst] +BasedOnStyles = Vale, NVIDIA + +# Skip inline Sphinx roles (:class:`...`, :const:`...`, etc.), Sphinx +# directive blocks (.. automodule:: ...), which rst2html leaves as text, +# and dotted code paths in prose: multi-segment (physicsnemo.metrics.mse) +# and lowercase two-segment (physicsnemo.mesh; first segment 2+ chars so +# "e.g."/"i.e." stay visible to NVIDIA.LatinAbbreviations). +TokenIgnores = (:[a-zA-Z:]+:`[^`]+`_?), (\b[A-Za-z_][\w]*\.[A-Za-z_][\w]*(?:\.[A-Za-z_][\w]*)+\b), (\b[a-z_][\w]+\.[a-z_][\w]*\b) +BlockIgnores = (?m)^\.\. [a-zA-Z:]+::[^\n]*(?:\n[ \t]+[^\n]*)* diff --git a/.vale/styles/NVIDIA/Adverbs.yml b/.vale/styles/NVIDIA/Adverbs.yml new file mode 100644 index 0000000000..dffb829044 --- /dev/null +++ b/.vale/styles/NVIDIA/Adverbs.yml @@ -0,0 +1,273 @@ +# Adapted from the MIT-licensed Microsoft style for Vale +# (https://github.com/errata-ai/Microsoft). +extends: existence +message: "Remove '%s' if it's not important to the meaning of the statement." +ignorecase: true +level: suggestion +action: + name: remove +tokens: + - abnormally + - absentmindedly + - accidentally + - adventurously + - anxiously + - arrogantly + - awkwardly + - bashfully + - beautifully + - bitterly + - bleakly + - blindly + - blissfully + - boastfully + - boldly + - bravely + - briefly + - brightly + - briskly + - broadly + - busily + - calmly + - carefully + - carelessly + - cautiously + - cheerfully + - cleverly + - closely + - coaxingly + - colorfully + - continually + - coolly + - courageously + - crossly + - cruelly + - curiously + - daintily + - dearly + - deceivingly + - deeply + - defiantly + - deliberately + - delightfully + - diligently + - dimly + - doubtfully + - dreamily + - easily + - effectively + - elegantly + - energetically + - enormously + - enthusiastically + - excitedly + - extremely + - fairly + - faithfully + - famously + - ferociously + - fervently + - fiercely + - fondly + - foolishly + - fortunately + - frankly + - frantically + - freely + - frenetically + - frightfully + - furiously + - generally + - generously + - gently + - gladly + - gleefully + - gracefully + - gratefully + - greatly + - greedily + - happily + - hastily + - healthily + - heavily + - helplessly + - honestly + - hopelessly + - hungrily + - innocently + - inquisitively + - intensely + - intently + - interestingly + - inwardly + - irritably + - jaggedly + - jealously + - jovially + - joyfully + - joyously + - jubilantly + - judgmentally + - justly + - keenly + - kiddingly + - kindheartedly + - knavishly + - knowingly + - knowledgeably + - lazily + - lightly + - limply + - lively + - loftily + - longingly + - loosely + - loudly + - lovingly + - loyally + - madly + - majestically + - meaningfully + - mechanically + - merrily + - miserably + - mockingly + - mortally + - mysteriously + - naturally + - nearly + - neatly + - nervously + - nicely + - noisily + - obediently + - obnoxiously + - oddly + - offensively + - optimistically + - overconfidently + - painfully + - partially + - patiently + - perfectly + - playfully + - politely + - poorly + - positively + - potentially + - powerfully + - promptly + - properly + - punctually + - quaintly + - queasily + - queerly + - questionably + - quickly + - quietly + - quirkily + - quite + - quizzically + - randomly + - rapidly + - rarely + - readily + - really + - reassuringly + - recklessly + - regularly + - reluctantly + - repeatedly + - reproachfully + - restfully + - righteously + - rightfully + - rigidly + - roughly + - rudely + - safely + - scarcely + - scarily + - searchingly + - sedately + - seemingly + - selfishly + - separately + - seriously + - shakily + - sharply + - sheepishly + - shrilly + - shyly + - silently + - sleepily + - slowly + - smoothly + - softly + - solemnly + - solidly + - speedily + - stealthily + - sternly + - strictly + - suddenly + - supposedly + - surprisingly + - suspiciously + - sweetly + - swiftly + - sympathetically + - tenderly + - tensely + - terribly + - thankfully + - thoroughly + - thoughtfully + - tightly + - tremendously + - triumphantly + - truthfully + - ultimately + - unabashedly + - unaccountably + - unbearably + - unethically + - unexpectedly + - unfortunately + - unimpressively + - unnaturally + - unnecessarily + - urgently + - usefully + - uselessly + - utterly + - vacantly + - vaguely + - vainly + - valiantly + - vastly + - verbally + - very + - viciously + - victoriously + - violently + - vivaciously + - voluntarily + - warmly + - weakly + - wearily + - wetly + - wholly + - wildly + - willfully + - wisely + - woefully + - wonderfully + - worriedly + - yawningly + - yearningly + - yieldingly + - youthfully + - zealously + - zestfully + - zestily diff --git a/.vale/styles/NVIDIA/Ampersand.yml b/.vale/styles/NVIDIA/Ampersand.yml new file mode 100644 index 0000000000..bade98ab18 --- /dev/null +++ b/.vale/styles/NVIDIA/Ampersand.yml @@ -0,0 +1,8 @@ +# House style: spell out "and" in prose and headings; "&" only in +# code, product names, or where space is constrained (tables). +extends: existence +message: "Use 'and' instead of '&' in prose and headings." +level: warning +nonword: true +raw: + - ' & ' diff --git a/.vale/styles/NVIDIA/Branding.yml b/.vale/styles/NVIDIA/Branding.yml new file mode 100644 index 0000000000..7663598921 --- /dev/null +++ b/.vale/styles/NVIDIA/Branding.yml @@ -0,0 +1,8 @@ +# NVIDIA writing guidelines: brand and product names use exact casing. +extends: substitution +message: "Use '%s' instead of '%s'." +level: error +ignorecase: false +swap: + '\b(?:Nvidia|nVidia|nVIDIA)\b': NVIDIA + '\b(?:NeMoTron|NemoTron)\b': Nemotron diff --git a/.vale/styles/NVIDIA/ConjunctiveAdverbs.yml b/.vale/styles/NVIDIA/ConjunctiveAdverbs.yml new file mode 100644 index 0000000000..f8276629e7 --- /dev/null +++ b/.vale/styles/NVIDIA/ConjunctiveAdverbs.yml @@ -0,0 +1,15 @@ +# NVIDIA writing guidelines (Technical Content > Readability): +# "Use academic or formal conjunctive adverbs sparingly." +extends: existence +message: "Use the formal conjunctive adverb '%s' sparingly." +level: suggestion +ignorecase: true +tokens: + - additionally + - consequently + - furthermore + - hence + - moreover + - thus + - undoubtedly + - whilst diff --git a/.vale/styles/NVIDIA/Contractions.yml b/.vale/styles/NVIDIA/Contractions.yml new file mode 100644 index 0000000000..2ec961e5ae --- /dev/null +++ b/.vale/styles/NVIDIA/Contractions.yml @@ -0,0 +1,27 @@ +# House style for formal technical documentation: expand contractions. +# (Replaces Microsoft.Contractions, which prefers the opposite.) +extends: substitution +message: "Use '%s' instead of '%s' in formal technical documentation." +level: warning +ignorecase: true +action: + name: replace +swap: + aren't: are not + can't: cannot + 'can not': cannot + couldn't: could not + didn't: did not + doesn't: does not + don't: do not + hasn't: has not + haven't: have not + isn't: is not + "it's": it is + shouldn't: should not + "that's": that is + wasn't: was not + weren't: were not + won't: will not + wouldn't: would not + "you're": you are diff --git a/.vale/styles/NVIDIA/FileExtensions.yml b/.vale/styles/NVIDIA/FileExtensions.yml new file mode 100644 index 0000000000..eed199aba5 --- /dev/null +++ b/.vale/styles/NVIDIA/FileExtensions.yml @@ -0,0 +1,9 @@ +# NVIDIA writing guidelines (Technical Content > File Name Extensions): +# Extensions are lowercase with a period (a .tgz file); file types are +# uppercase without a period (a TGZ file). +extends: existence +message: "Use lowercase for file name extensions ('%s'); reserve uppercase (no period) for the file type." +level: warning +ignorecase: false +raw: + - '\.(?:ZIP|TAR|TGZ|GZ|BZ2|PDF|PNG|JPE?G|GIF|SVG|YAML|YML|JSON|XML|CSV|TXT|PY|RST|MD|SH|EXE|DEB|RPM|ONNX|WHL|HTML?)\b' diff --git a/.vale/styles/NVIDIA/GitHubRepo.yml b/.vale/styles/NVIDIA/GitHubRepo.yml new file mode 100644 index 0000000000..cd68765821 --- /dev/null +++ b/.vale/styles/NVIDIA/GitHubRepo.yml @@ -0,0 +1,9 @@ +# NVIDIA writing guidelines (Technical Content > GitHub Repositories): +# "Use a forward slash and a repository name for GitHub links." +# Correct: the /NVIDIA/NeMo GitHub repo. Incorrect: the GitHub repo. +extends: existence +message: "Name the repository when referring to it, e.g. 'the /NVIDIA/PhysicsNeMo GitHub repo'." +level: suggestion +ignorecase: true +raw: + - '\bthe GitHub repo(?:sitory)?\b' diff --git a/.vale/styles/NVIDIA/LatinAbbreviations.yml b/.vale/styles/NVIDIA/LatinAbbreviations.yml new file mode 100644 index 0000000000..39906b1cde --- /dev/null +++ b/.vale/styles/NVIDIA/LatinAbbreviations.yml @@ -0,0 +1,13 @@ +# Spell out Latin abbreviations in prose (per tech-writer convention: +# "e.g." becomes "for example"). Adapted from the MIT-licensed Microsoft +# style for Vale. +extends: substitution +message: "Use '%s' instead of '%s'." +ignorecase: true +level: error +nonword: true +action: + name: replace +swap: + '\b(?:eg|e\.g\.)[\s,]': for example + '\b(?:ie|i\.e\.)[\s,]': that is diff --git a/.vale/styles/NVIDIA/MarketingClaims.yml b/.vale/styles/NVIDIA/MarketingClaims.yml new file mode 100644 index 0000000000..20d3bb86ea --- /dev/null +++ b/.vale/styles/NVIDIA/MarketingClaims.yml @@ -0,0 +1,18 @@ +# NVIDIA writing guidelines (Technical Content > Marketing Claims): +# "Avoid flowery language or comparisons with third-party products." +extends: existence +message: "Avoid flowery marketing language like '%s' in technical content." +level: warning +ignorecase: true +tokens: + - supercharged? + - "world's leading" + - world-leading + - game-changing + - revolutionary + - groundbreaking + - cutting-edge + - best-in-class + - blazing(?:ly)?[- ]fast + - unparalleled + - unrivaled diff --git a/.vale/styles/NVIDIA/Passive.yml b/.vale/styles/NVIDIA/Passive.yml new file mode 100644 index 0000000000..de4c4264b1 --- /dev/null +++ b/.vale/styles/NVIDIA/Passive.yml @@ -0,0 +1,185 @@ +# Adapted from the MIT-licensed Microsoft style for Vale +# (https://github.com/errata-ai/Microsoft). +extends: existence +message: "'%s' looks like passive voice." +ignorecase: true +level: suggestion +raw: + - \b(am|are|were|being|is|been|was|be)\b\s* +tokens: + - '[\w]+ed' + - awoken + - beat + - become + - been + - begun + - bent + - beset + - bet + - bid + - bidden + - bitten + - bled + - blown + - born + - bought + - bound + - bred + - broadcast + - broken + - brought + - built + - burnt + - burst + - cast + - caught + - chosen + - clung + - come + - cost + - crept + - cut + - dealt + - dived + - done + - drawn + - dreamt + - driven + - drunk + - dug + - eaten + - fallen + - fed + - felt + - fit + - fled + - flown + - flung + - forbidden + - foregone + - forgiven + - forgotten + - forsaken + - fought + - found + - frozen + - given + - gone + - gotten + - ground + - grown + - heard + - held + - hidden + - hit + - hung + - hurt + - kept + - knelt + - knit + - known + - laid + - lain + - leapt + - learnt + - led + - left + - lent + - let + - lighted + - lost + - made + - meant + - met + - misspelt + - mistaken + - mown + - overcome + - overdone + - overtaken + - overthrown + - paid + - pled + - proven + - put + - quit + - read + - rid + - ridden + - risen + - run + - rung + - said + - sat + - sawn + - seen + - sent + - set + - sewn + - shaken + - shaven + - shed + - shod + - shone + - shorn + - shot + - shown + - shrunk + - shut + - slain + - slept + - slid + - slit + - slung + - smitten + - sold + - sought + - sown + - sped + - spent + - spilt + - spit + - split + - spoken + - spread + - sprung + - spun + - stolen + - stood + - stridden + - striven + - struck + - strung + - stuck + - stung + - stunk + - sung + - sunk + - swept + - swollen + - sworn + - swum + - swung + - taken + - taught + - thought + - thrived + - thrown + - thrust + - told + - torn + - trodden + - understood + - upheld + - upset + - wed + - wept + - withheld + - withstood + - woken + - won + - worn + - wound + - woven + - written + - wrung diff --git a/.vale/styles/NVIDIA/Reference.yml b/.vale/styles/NVIDIA/Reference.yml new file mode 100644 index 0000000000..3af4341bcf --- /dev/null +++ b/.vale/styles/NVIDIA/Reference.yml @@ -0,0 +1,8 @@ +# House style (per tech-writer convention): direct readers with +# "refer to" rather than "see". +extends: existence +message: "Prefer 'refer to' over 'see' when directing readers to other content." +level: suggestion +ignorecase: true +tokens: + - 'see (?:the|this|these|those|above|below|also)\b' diff --git a/.vale/styles/NVIDIA/Semicolon.yml b/.vale/styles/NVIDIA/Semicolon.yml new file mode 100644 index 0000000000..906f7b5398 --- /dev/null +++ b/.vale/styles/NVIDIA/Semicolon.yml @@ -0,0 +1,9 @@ +# Adapted from the MIT-licensed Microsoft style for Vale +# (https://github.com/errata-ai/Microsoft). +extends: existence +message: "Try to simplify this sentence." +nonword: true +scope: sentence +level: suggestion +tokens: + - ';' diff --git a/.vale/styles/NVIDIA/SentenceLength.yml b/.vale/styles/NVIDIA/SentenceLength.yml new file mode 100644 index 0000000000..cb7979e4e5 --- /dev/null +++ b/.vale/styles/NVIDIA/SentenceLength.yml @@ -0,0 +1,8 @@ +# Adapted from the MIT-licensed Microsoft style for Vale +# (https://github.com/errata-ai/Microsoft). +extends: occurrence +message: "Try to keep sentences short (< 30 words)." +scope: sentence +level: suggestion +max: 30 +token: \b(\w+)\b diff --git a/.vale/styles/NVIDIA/Snippet.yml b/.vale/styles/NVIDIA/Snippet.yml new file mode 100644 index 0000000000..9d8babf447 --- /dev/null +++ b/.vale/styles/NVIDIA/Snippet.yml @@ -0,0 +1,8 @@ +# NVIDIA writing guidelines (Technical Content > Code Elements or Examples): +# "Avoid using the term snippet." +extends: existence +message: "Avoid the term '%s'; use 'code example' instead." +level: warning +ignorecase: true +tokens: + - snippets? diff --git a/.vale/styles/NVIDIA/Spacing.yml b/.vale/styles/NVIDIA/Spacing.yml new file mode 100644 index 0000000000..c834e15dac --- /dev/null +++ b/.vale/styles/NVIDIA/Spacing.yml @@ -0,0 +1,9 @@ +# One space between sentences. (Adapted from the MIT-licensed Microsoft +# style for Vale; the missing-space token was dropped because it +# false-positives on dotted code paths like physicsnemo.mesh.Mesh.) +extends: existence +message: "'%s' should have one space." +level: error +nonword: true +tokens: + - '[a-z][.?!] {2,}[A-Z]' diff --git a/.vale/styles/NVIDIA/Terms.yml b/.vale/styles/NVIDIA/Terms.yml new file mode 100644 index 0000000000..d83a3cc00f --- /dev/null +++ b/.vale/styles/NVIDIA/Terms.yml @@ -0,0 +1,10 @@ +# House style word choices observed in tech-writer edits. +extends: substitution +message: "Use '%s' instead of '%s'." +level: warning +ignorecase: true +action: + name: replace +swap: + via: through + 'just like': like diff --git a/.vale/styles/NVIDIA/We.yml b/.vale/styles/NVIDIA/We.yml new file mode 100644 index 0000000000..12b9a06a55 --- /dev/null +++ b/.vale/styles/NVIDIA/We.yml @@ -0,0 +1,12 @@ +# Adapted from the MIT-licensed Microsoft style for Vale +# (https://github.com/errata-ai/Microsoft). +extends: existence +message: "Try to avoid using first-person plural like '%s'." +level: suggestion +ignorecase: true +tokens: + - we + - we'(?:ve|re) + - ours? + - us + - let's diff --git a/.vale/styles/NVIDIA/Wordiness.yml b/.vale/styles/NVIDIA/Wordiness.yml new file mode 100644 index 0000000000..3169878d0b --- /dev/null +++ b/.vale/styles/NVIDIA/Wordiness.yml @@ -0,0 +1,128 @@ +# Adapted from the MIT-licensed Microsoft style for Vale +# (https://github.com/errata-ai/Microsoft). +extends: substitution +message: "Consider using '%s' instead of '%s'." +ignorecase: true +level: suggestion +action: + name: replace +swap: + "sufficient number(?: of)?": enough + (?:extract|take away|eliminate): remove + (?:in order to|as a means to): to + (?:inform|let me know): tell + (?:previous|prior) to: before + (?:utilize|make use of): use + a (?:large)? majority of: most + a (?:large)? number of: many + a myriad of: myriad + adversely impact: hurt + all across: across + all of a sudden: suddenly + all of these: these + all of(?! a sudden| these): all + all-time record: record + almost all: most + almost never: seldom + along the lines of: similar to + an adequate number of: enough + an appreciable number of: many + an estimated: about + any and all: all + are in agreement: agree + as a matter of fact: in fact + as a means of: to + as a result of: because of + as of yet: yet + as per: per + at a later date: later + at all times: always + at the present time: now + at this point in time: at this point + based in large part on: based on + based on the fact that: because + basic necessity: necessity + because of the fact that: because + came to a realization: realized + came to an abrupt end: ended abruptly + carry out an evaluation of: evaluate + close down: close + closed down: closed + complete stranger: stranger + completely separate: separate + concerning the matter of: regarding + conduct a review of: review + conduct an investigation: investigate + conduct experiments: experiment + continue on: continue + despite the fact that: although + disappear from sight: disappear + doomed to fail: doomed + drag and drop: drag + drag-and-drop: drag + due to the fact that: because + during the period of: during + during the time that: while + emergency situation: emergency + establish connectivity: connect + except when: unless + excessive number: too many + extend an invitation: invite + fall down: fall + fell down: fell + for the duration of: during + gather together: gather + has the ability to: can + has the capacity to: can + has the opportunity to: could + hold a meeting: meet + if this is not the case: if not + in a careful manner: carefully + in a thoughtful manner: thoughtfully + in a timely manner: timely + in addition: also + in an effort to: to + in between: between + in lieu of: instead of + in many cases: often + in most cases: usually + in order to: to + in some cases: sometimes + in spite of the fact that: although + in spite of: despite + in the (?:very)? near future: soon + in the event that: if + in the neighborhood of: roughly + in the vicinity of: close to + it would appear that: apparently + lift up: lift + made reference to: referred to + make reference to: refer to + mix together: mix + none at all: none + not in a position to: unable + not possible: impossible + of major importance: important + perform an assessment of: assess + pertaining to: about + place an order: order + plays a key role in: is essential to + present time: now + readily apparent: apparent + some of the: some + span across: span + subsequent to: after + successfully complete: complete + take action: act + take into account: consider + the question as to whether: whether + there is no doubt but that: doubtless + this day and age: this age + this is a subject that: this subject + time (?:frame|period): time + under the provisions of: under + until such time as: until + used for fuel purposes: used for fuel + whether or not: whether + with regard to: regarding + with the exception of: except for diff --git a/.vale/styles/config/vocabularies/NVIDIA/accept.txt b/.vale/styles/config/vocabularies/NVIDIA/accept.txt new file mode 100644 index 0000000000..8b7f07af10 --- /dev/null +++ b/.vale/styles/config/vocabularies/NVIDIA/accept.txt @@ -0,0 +1,117 @@ +NVIDIA +PhysicsNeMo +CUDA +cuDNN +NCCL +PyTorch +Sphinx +ONNX +TensorRT +Modulus +GitHub +Hydra +Warp +TensorDict +DataLoader +PyG +Zarr +MLflow +HEALPix +Transolver +DTensor +VTKReader +UNets? +(?i)timm +(?i)numpy +(?i)matplotlib +[Aa]utograd +async +bool +repr +(?i)cpus? +np +dtype +classmethod +namespace +tensorclass +(?i)datapipes? +[Ii]terable +[Cc]omposab(?:le|ility) +pipelining +preload +backpressure +[Cc]heckpoint(?:ing|ed) +performant +[Pp]ythonic +APIs +GPUs +FNOs +BCs +(?i)cae +(?i)gnns? +pretrained +[Ee]lectromagnetics +chatbot +[Pp]arallelization +[Pp]arameterizations? +[Dd]iscretizations? +[Tt]okenization +sharding +[Ss]ubsampl(?:e|es|ed|ing) +[Dd]ownsampl(?:e|es|ed|ing) +[Dd]ownscaling +[Rr]esampling +[Uu]psampl(?:e|es|ed|ing) +[Dd]enois(?:e|er|ers|ed|ing) +[Pp]reconditioners? +subclassed +learnable +autoregressive +rollout +backpropagation +inpainting +bitwise +initializer +lookups +deduplicates? +unreferenced +guidances +equivariance +multilinear +linearithmic +centroidal +[Cc]odimension +[Ii]nterop +[Ss]implicial +simplices +tetrahedra +[Ii]sosurfaces? +[Cc]ircumcent(?:ers|ric) +Voronoi +[Mm]esher +[Rr]emesh(?:ing|ed)? +[Tt]essellation +[Vv]oxels? +[Ww]ireframe +[Rr]aycast +colormapp(?:ed|ing) +wetted +(?i)bvh +[Ff]unctionals? +[Oo]ptim +[Uu]tils +Wasserstein +Zorin +Desbrun +Hirani +Leok +Marsden +Ruppert +Greville +Xie +# snake_case identifiers are code, not prose; do not spell-check them +[A-Za-z]\w*_[\w_]+ +(?:un)?patchif(?:y|ies|ied) +scheduler's +Geometric's +_[\w_]+