Script to generate docs for types and updated docs/types.md #2080
Conversation
|
Deploy preview for babel failed. Built without sensitive environment variables with commit 9cd3f21 https://app.netlify.com/sites/babel/deploys/5fa51bdcc1a8640008299a7c |
|
Not sure why there was merge conflicts here, but it looks like masters diff didn't like the re-ordering of the methods. Did a search to see that I didn't remove anything, but haven't checked for duplicates. |
| const sections = []; | ||
|
|
||
| for (const type in t) { | ||
| const isBuilder = /_builder\.default/.test(t[type].toString()); |
There was a problem hiding this comment.
I think we should include not just the builder, but as well as assert* and is* utility functions
| see.is = type; | ||
| } | ||
| } | ||
| return `See also \`t.${see.is}(node, opts)\` and \`t.${ |
There was a problem hiding this comment.
what if see.is or see.assert is not available, wouldn't it be See also and ?
maybe a join with " and " would be better?
There was a problem hiding this comment.
and if we adding is and assert section, maybe this can be a link to the section
scripts/generate-docs-types.js
Outdated
| @@ -0,0 +1,287 @@ | |||
| const fs = require("fs"); | |||
| const path = require("path"); | |||
| const t = require("@babel/types"); | |||
There was a problem hiding this comment.
Can we make this configurable, to be able to generate them from master?
node scripts/generate-docs-types.js --path ../babel/packages/babel-types
scripts/generate-docs-types.js
Outdated
| const { promisify } = require("util"); | ||
|
|
||
| const readfile = promisify(fs.readFile); | ||
| const writefile = promisify(fs.writeFile); |
There was a problem hiding this comment.
You can do const fs = require("fs").promises instead
| @@ -0,0 +1,72 @@ | |||
| const fs = require("fs"); | |||
There was a problem hiding this comment.
Do we need this file? Ideally we would only need to generate docs for the new current version in the future.
|
Good suggestions, I'll hopefully get around to picking this up again soon. Time flies. |
deificx
force-pushed
the
generate-babel-types-docs
branch
from
7dff70e to
9cd3f21
Compare
It does indeed, but better late than never I've heard. The conflicts seem to be where there is additional data about when something was added, I might need to handle that case as well then. In addition to generating the documents I've also tried to create some examples. They aren't always great, like f.ex. |
I ended up writing a script to generate this documentation based of type definitions found in
node_modules/@babel/types/lib/index.d.ts. It does so by looking through the properties of the export from@babel/types, seeing which functions (when turned to string, which is not a great idea) includes a call to_builder.default, then it looks into theindex.d.tsfile above, yet again using Regex and string matching, to extract the types.This script is run by another script
scripts/generate-docs-types-versions.jswhich creates a directory for each version, installs that version and generates thetypes.mdusingscripts/generate-docs-types.js. It's not exactly pretty, but it works.I tried to keep line spacing and such similar to keep the diff as small as possible.
I'm not sure what to do with the version doc for version-6.26.3, as I'm not able to locate the babel package for that on npm.
Notable changes
Aliases, even if there are none.[])false)"")null)t.tsUnknownType(types)"renamed"t.tsUnknownKeyword(), fixes t.tsUnknownType is documented but doesn't exist #2079t.import()has disappeared.