DOCSP-4283 Validate code examples #219
Conversation
cbush
requested review from
MongoCaleb,
adamchel,
dkaminsky,
edaniels and
jsflax
adamchel
left a comment
adamchel
left a comment
There was a problem hiding this comment.
LGTM, this is really neat! One optional thing that you could do so we catch broken code examples before they get released is to add an evergreen task to validate the samples. If you don't know how to do that, DM me on slack and I can help.
| @@ -1,5 +1,5 @@ | |||
| { | |||
| "name": "stitch-js-sdk", | |||
| "name": "stitch-js-sdk", | |||
There was a problem hiding this comment.
[nit] I can't tell if these are tabs or spaces from the Github interface, but make sure it's consistent across the whole file.
| "scripts": { | ||
| "docs": "npm run docs-theme && npm run docs-browser && npm run docs-server && npm run docs-react-native", | ||
| "docs-theme": "pushd typedoc-theme && npm run build", | ||
| "docs-theme": "pushd typedoc-theme && npm run build", |
There was a problem hiding this comment.
You're right. Good catch! But I think this change actually makes it consistent now.
nlarew
left a comment
nlarew
left a comment
There was a problem hiding this comment.
LGTM % One question / potentially missing piece
| @@ -0,0 +1,35 @@ | |||
|
|
|||
| // ^^^ Paste example() definition ^^^ | |||
There was a problem hiding this comment.
Do we need to "bring our own" example function or should we add one in here? If the former, maybe add a couple sentences that explain the situation.
There was a problem hiding this comment.
Examples are pasted automatically by the validate.sh script. Will add note!
- Externalizes code examples in contrib/docs-examples/snippets. - Adds validator script. Not so much a unit test as just running eslint and the script itself to check that the script is formatted and the APIs are still valid, etc. - Adds two TypeDoc plugins: code-examples and tags-by-name - code-examples plugin pastes code examples from external files to the comment tags of a matching-named entity - tags-by-name reorders the TypeDoc tags of each entity to be more usable by the custom TypeDoc theme. - Updates the custom theme to use the new examples tags and also the "See also" tag. - Updates all code examples to use @example tag or remove the example. - Updates comments to use @see instead of See Also. - Validator caveat: it actually runs in the 'server' context.
cbush
force-pushed
the
docsp-4283-code-example-validation
branch
from
06fa4ca to
2736c0f
Compare
5 participants
eslint and the script itself to check that the script is formatted
and the APIs are still valid, etc.
the comment tags of a matching-named entity
usable by the custom TypeDoc theme.
the "See also" tag.
Staged changes:
https://docs-mongodbcom-staging.corp.mongodb.com/stitch/bush/docsp-4283-code-example-validation/sdk/js/index.html
https://docs-mongodbcom-staging.corp.mongodb.com/stitch/bush/docsp-4283-code-example-validation/sdk/js-server/index.html
https://docs-mongodbcom-staging.corp.mongodb.com/stitch/bush/docsp-4283-code-example-validation/sdk/react-native/index.html