From 662dcb01e2e8d557dd83930403e3f304a81be17f Mon Sep 17 00:00:00 2001 From: "Fred K. Schott" Date: Mon, 30 Jan 2023 06:08:55 -0800 Subject: [PATCH] wip --- .gitignore | 1 + examples/with-content/.astro/types.d.ts | 87 +++++++++ package.json | 1 + packages/astro/src/@types/astro.ts | 1 + pnpm-lock.yaml | 235 +++++++++++++++++++++++- scripts/docs/docgen.js | 100 ++++++++++ 6 files changed, 424 insertions(+), 1 deletion(-) create mode 100644 examples/with-content/.astro/types.d.ts create mode 100644 scripts/docs/docgen.js diff --git a/.gitignore b/.gitignore index df661ac83..00e49d4fe 100644 --- a/.gitignore +++ b/.gitignore @@ -21,6 +21,7 @@ package-lock.json packages/astro/src/**/*.prebuilt.ts !packages/astro/vendor/vite/dist packages/integrations/**/.netlify/ +packages/astro/reference # exclude IntelliJ/WebStorm stuff .idea diff --git a/examples/with-content/.astro/types.d.ts b/examples/with-content/.astro/types.d.ts new file mode 100644 index 000000000..19a60e803 --- /dev/null +++ b/examples/with-content/.astro/types.d.ts @@ -0,0 +1,87 @@ +declare module 'astro:content' { + export { z } from 'astro/zod'; + export type CollectionEntry = + (typeof entryMap)[C][keyof (typeof entryMap)[C]] & Render; + + type BaseSchemaWithoutEffects = + | import('astro/zod').AnyZodObject + | import('astro/zod').ZodUnion + | import('astro/zod').ZodDiscriminatedUnion + | import('astro/zod').ZodIntersection< + import('astro/zod').AnyZodObject, + import('astro/zod').AnyZodObject + >; + + type BaseSchema = + | BaseSchemaWithoutEffects + | import('astro/zod').ZodEffects; + + type BaseCollectionConfig = { + schema?: S; + }; + export function defineCollection( + input: BaseCollectionConfig + ): BaseCollectionConfig; + + export function getEntry( + collection: C, + entryKey: E + ): Promise<(typeof entryMap)[C][E] & Render>; + export function getCollection< + C extends keyof typeof entryMap, + E extends keyof (typeof entryMap)[C] + >( + collection: C, + filter?: (data: (typeof entryMap)[C][E]) => boolean + ): Promise<((typeof entryMap)[C][E] & Render)[]>; + + type InferEntrySchema = import('astro/zod').infer< + Required['schema'] + >; + + type Render = { + render(): Promise<{ + Content: import('astro').MarkdownInstance<{}>['Content']; + headings: import('astro').MarkdownHeading[]; + remarkPluginFrontmatter: Record; + }>; + }; + + const entryMap: { + "blog": { +"first-post": { + id: "first-post", + body: string, + collection: "blog", + data: InferEntrySchema<"blog"> +}, +"markdown-style-guide": { + id: "markdown-style-guide", + body: string, + collection: "blog", + data: InferEntrySchema<"blog"> +}, +"second-post": { + id: "second-post", + body: string, + collection: "blog", + data: InferEntrySchema<"blog"> +}, +"third-post": { + id: "third-post", + body: string, + collection: "blog", + data: InferEntrySchema<"blog"> +}, +"using-mdx": { + id: "using-mdx", + body: string, + collection: "blog", + data: InferEntrySchema<"blog"> +}, +}, + + }; + + type ContentConfig = typeof import("../src/content/config"); +} diff --git a/package.json b/package.json index f119d34d0..aad116f15 100644 --- a/package.json +++ b/package.json @@ -92,6 +92,7 @@ "eslint-plugin-no-only-tests": "^2.6.0", "eslint-plugin-prettier": "^4.0.0", "execa": "^6.1.0", + "jsdoc-api": "^8.0.0", "only-allow": "^1.1.1", "organize-imports-cli": "^0.10.0", "prettier": "^2.7.0", diff --git a/packages/astro/src/@types/astro.ts b/packages/astro/src/@types/astro.ts index c1c5f585a..bb0412f80 100644 --- a/packages/astro/src/@types/astro.ts +++ b/packages/astro/src/@types/astro.ts @@ -734,6 +734,7 @@ export interface AstroUserConfig { /** * @docs * @name markdown.syntaxHighlight + * @category config * @type {'shiki' | 'prism' | false} * @default `shiki` * @description diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index f3d979e5d..451779500 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -28,6 +28,7 @@ importers: eslint-plugin-no-only-tests: ^2.6.0 eslint-plugin-prettier: ^4.0.0 execa: ^6.1.0 + jsdoc-api: ^8.0.0 only-allow: ^1.1.1 organize-imports-cli: ^0.10.0 prettier: ^2.7.0 @@ -52,6 +53,7 @@ importers: eslint-plugin-no-only-tests: 2.6.0 eslint-plugin-prettier: 4.2.1_iu5s7nk6dw7o3tajefwfiqfmge execa: 6.1.0 + jsdoc-api: 8.0.0 only-allow: 1.1.1 organize-imports-cli: 0.10.0 prettier: 2.8.2 @@ -6084,6 +6086,13 @@ packages: resolution: {integrity: sha512-n5JEf16Wr4mdkRMZ8wMP/wN9/sHmTjRPbouXjJH371mZ2LEGDl72t8tEsMRNFerQN/QJtivOxqK1frdGa4QK5Q==} engines: {node: '>=10'} + /@jsdoc/salty/0.2.3: + resolution: {integrity: sha512-bbtCxCkxcnWhi50I+4Lj6mdz9w3pOXOgEQrID8TCZ/DF51fW7M9GCQW2y45SpBDdHd1Eirm1X/Cf6CkAAe8HPg==} + engines: {node: '>=v12.0.0'} + dependencies: + lodash: 4.17.21 + dev: true + /@lit-labs/ssr-client/1.0.1: resolution: {integrity: sha512-rr/UVhxbKWNUr+3qRyvZk+glC7v7ph8Gk/W0z96YG64COJKf9ilnWY6JGW77TRqhrRMmS2nsvAXOyQgcF+4jrA==} dependencies: @@ -6966,11 +6975,26 @@ packages: /@types/json5/0.0.30: resolution: {integrity: sha512-sqm9g7mHlPY/43fcSNrCYfOeX9zkTTK+euO5E6+CVijSMm5tTjkVdwdqRkY3ljjIAf8679vps5jKUoJBCLsMDA==} + /@types/linkify-it/3.0.2: + resolution: {integrity: sha512-HZQYqbiFVWufzCwexrvh694SOim8z2d+xJl5UNamcvQFejLY/2YUtzXHYi3cHdI7PMlS8ejH2slRAOJQ32aNbA==} + dev: true + + /@types/markdown-it/12.2.3: + resolution: {integrity: sha512-GKMHFfv3458yYy+v/N8gjufHO6MSZKCOXpZc5GXIWWy8uldwfmPn98vp81gZ5f9SVw8YYBctgfJ22a2d7AOMeQ==} + dependencies: + '@types/linkify-it': 3.0.2 + '@types/mdurl': 1.0.2 + dev: true + /@types/mdast/3.0.10: resolution: {integrity: sha512-W864tg/Osz1+9f4lrGTZpCSO5/z4608eUp19tbozkq2HJK6i3z1kT0H9tlADXuYIb1YYOBByU4Jsqkk75q48qA==} dependencies: '@types/unist': 2.0.6 + /@types/mdurl/1.0.2: + resolution: {integrity: sha512-eC4U9MlIcu2q0KQmXszyn5Akca/0jrQmwDRgpAMJai7qBWq4amIQhZyNau4VYGtCeALvW1/NtjzJJ567aZxfKA==} + dev: true + /@types/mdx/2.0.3: resolution: {integrity: sha512-IgHxcT3RC8LzFLhKwP3gbMPeaK7BM9eBH46OdapPA7yvuIUJ8H6zHZV53J8hGZcTSnt95jANt+rTBNUUc22ACQ==} dev: false @@ -7795,6 +7819,28 @@ packages: resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==} dev: true + /array-back/1.0.4: + resolution: {integrity: sha512-1WxbZvrmyhkNoeYcizokbmh5oiOCIfyvGtcqbK3Ls1v1fKcquzxnQSceOx6tzq7jmai2kFLWIpGND2cLhH6TPw==} + engines: {node: '>=0.12.0'} + dependencies: + typical: 2.6.1 + dev: true + + /array-back/4.0.2: + resolution: {integrity: sha512-NbdMezxqf94cnNfWLL7V/im0Ub+Anbb0IoZhvzie8+4HJ4nMQuzHuy49FkGYCJK2yAloZ3meiB6AVMClbrI1vg==} + engines: {node: '>=8'} + dev: true + + /array-back/5.0.0: + resolution: {integrity: sha512-kgVWwJReZWmVuWOQKEOohXKJX+nD02JAZ54D1RRWlv8L0NebauKAaFxACKzB74RTclt1+WNz5KHaLRDAPZbDEw==} + engines: {node: '>=10'} + dev: true + + /array-back/6.2.2: + resolution: {integrity: sha512-gUAZ7HPyb4SJczXAMUXMGAvI976JoK3qEx9v1FTmeYuJj0IBiaKttG1ydtGKdkfqWkIkouke7nG8ufGy77+Cvw==} + engines: {node: '>=12.17'} + dev: true + /array-iterate/2.0.1: resolution: {integrity: sha512-I1jXZMjAgCMmxT4qxXfPXa6SthSoE8h6gkSI9BGGNv8mP8G/v0blc+qFnZu6K42vTOiuME596QaLO0TP3Lk0xg==} dev: false @@ -8022,6 +8068,10 @@ packages: resolution: {integrity: sha512-F1+K8EbfOZE49dtoPtmxUQrpXaBIl3ICvasLh+nJta0xkz+9kF/7uet9fLnwKqhDrmj6g+6K3Tw9yQPUg2ka5g==} dev: true + /bluebird/3.7.2: + resolution: {integrity: sha512-XpNj6GDQzdfW+r2Wnn7xiSAd7TM3jzkxGXBGTtWKuSXv1xUV+azxAm8jdWZN06QTQk+2N2XB9jRDkvbmQmcRtg==} + dev: true + /boolbase/1.0.0: resolution: {integrity: sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==} @@ -8136,6 +8186,15 @@ packages: engines: {node: '>=8'} dev: false + /cache-point/2.0.0: + resolution: {integrity: sha512-4gkeHlFpSKgm3vm2gJN5sPqfmijYRFYCQ6tv5cLw0xVmT6r1z1vd4FNnpuOREco3cBs1G709sZ72LdgddKvL5w==} + engines: {node: '>=8'} + dependencies: + array-back: 4.0.2 + fs-then-native: 2.0.0 + mkdirp2: 1.0.5 + dev: true + /call-bind/1.0.2: resolution: {integrity: sha512-7O+FbCihrB5WGbFYesctwmTKae6rOiIzmz1icreWJ+0aA7LJfuqhEso2T9ncpcFtzMQtzXf2QGGueWJGTYsqrA==} dependencies: @@ -8176,6 +8235,13 @@ packages: resolution: {integrity: sha512-ej+w/m8Jzpv9Z7W7uJZer14Ke8P2ogsjg4ZMGIuq4iqUOqY2Jq8BNW42iGmNfRwREaaEfFIczLuZZiEVSYNHAA==} dev: false + /catharsis/0.9.0: + resolution: {integrity: sha512-prMTQVpcns/tzFgFVkVp6ak6RykZyWb3gu8ckUpd6YkTlacOd3DXGJjIpD4Q6zJirizvaiAjSSHlOsA+6sNh2A==} + engines: {node: '>= 10'} + dependencies: + lodash: 4.17.21 + dev: true + /ccount/2.0.1: resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==} @@ -8368,6 +8434,14 @@ packages: resolution: {integrity: sha512-NiujjUFB4SwScJq2bwbYUtXbZhBSlY6vYzm++3Q6oC+U+injTqfPYFK8wS9COOmb2lueqp0ZRB4nK1VYeHgNyw==} dev: true + /collect-all/1.0.4: + resolution: {integrity: sha512-RKZhRwJtJEP5FWul+gkSMEnaK6H3AGPTTWOiRimCcs+rc/OmQE3Yhy1Q7A7KsdkG3ZXVdZq68Y6ONSdvkeEcKA==} + engines: {node: '>=0.10.0'} + dependencies: + stream-connect: 1.0.2 + stream-via: 1.0.4 + dev: true + /color-convert/1.9.3: resolution: {integrity: sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==} dependencies: @@ -8972,6 +9046,10 @@ packages: ansi-colors: 4.1.3 dev: true + /entities/2.1.0: + resolution: {integrity: sha512-hCx1oky9PFrJ611mf0ifBLBRW8lUUVRlFolb5gWRfIELabBlbp9xZvrqZLZAs+NxFnbfQoeGd8wDkygjg7U85w==} + dev: true + /entities/4.4.0: resolution: {integrity: sha512-oYp7156SP8LkeGD0GF85ad1X9Ai79WtRsZ2gxJqtBuzH+98YUV6jkHEKlZkMbcrjJjIVJNIDP/3WL9wQkoPbWA==} engines: {node: '>=0.12'} @@ -9496,6 +9574,11 @@ packages: resolution: {integrity: sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==} engines: {node: '>=0.8.0'} + /escape-string-regexp/2.0.0: + resolution: {integrity: sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==} + engines: {node: '>=8'} + dev: true + /escape-string-regexp/4.0.0: resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==} engines: {node: '>=10'} @@ -9853,6 +9936,14 @@ packages: flat-cache: 3.0.4 dev: true + /file-set/4.0.2: + resolution: {integrity: sha512-fuxEgzk4L8waGXaAkd8cMr73Pm0FxOVkn8hztzUW7BAHhOGH90viQNXbiOsnecCWmfInqU6YmAMwxRMdKETceQ==} + engines: {node: '>=10'} + dependencies: + array-back: 5.0.0 + glob: 7.2.3 + dev: true + /file-uri-to-path/1.0.0: resolution: {integrity: sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw==} dev: false @@ -9991,6 +10082,11 @@ packages: resolution: {integrity: sha512-cybjIfiiE+pTWicSCLFHSrXZ6EilF30oh91FDP9S2B051prEa7QWfrVTQm10/dDpswBDXZugPa1Ogu8Yh+HV0Q==} dev: true + /fs-then-native/2.0.0: + resolution: {integrity: sha512-X712jAOaWXkemQCAmWeg5rOT2i+KOpWz1Z/txk/cW0qlOu2oQ9H61vc5w3X/iyuUEfq/OyaFJ78/cZAQD1/bgA==} + engines: {node: '>=4.0.0'} + dev: true + /fs.realpath/1.0.0: resolution: {integrity: sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==} @@ -10993,6 +11089,49 @@ packages: argparse: 2.0.1 dev: true + /js2xmlparser/4.0.2: + resolution: {integrity: sha512-6n4D8gLlLf1n5mNLQPRfViYzu9RATblzPEtm1SthMX1Pjao0r9YI9nw7ZIfRxQMERS87mcswrg+r/OYrPRX6jA==} + dependencies: + xmlcreate: 2.0.4 + dev: true + + /jsdoc-api/8.0.0: + resolution: {integrity: sha512-Rnhor0suB1Ds1abjmFkFfKeD+kSMRN9oHMTMZoJVUrmtCGDwXty+sWMA9sa4xbe4UyxuPjhC7tavZ40mDKK6QQ==} + engines: {node: '>=12.17'} + dependencies: + array-back: 6.2.2 + cache-point: 2.0.0 + collect-all: 1.0.4 + file-set: 4.0.2 + fs-then-native: 2.0.0 + jsdoc: 4.0.0 + object-to-spawn-args: 2.0.1 + temp-path: 1.0.0 + walk-back: 5.1.0 + dev: true + + /jsdoc/4.0.0: + resolution: {integrity: sha512-tzTgkklbWKrlaQL2+e3NNgLcZu3NaK2vsHRx7tyHQ+H5jcB9Gx0txSd2eJWlMC/xU1+7LQu4s58Ry0RkuaEQVg==} + engines: {node: '>=12.0.0'} + hasBin: true + dependencies: + '@babel/parser': 7.20.7 + '@jsdoc/salty': 0.2.3 + '@types/markdown-it': 12.2.3 + bluebird: 3.7.2 + catharsis: 0.9.0 + escape-string-regexp: 2.0.0 + js2xmlparser: 4.0.2 + klaw: 3.0.0 + markdown-it: 12.3.2 + markdown-it-anchor: 8.6.6_2zb4u3vubltivolgu556vv4aom + marked: 4.2.12 + mkdirp: 1.0.4 + requizzle: 0.2.4 + strip-json-comments: 3.1.1 + underscore: 1.13.6 + dev: true + /jsesc/0.5.0: resolution: {integrity: sha512-uZz5UnB7u4T9LvwmFqXii7pZSouaRPorGs5who1Ip7VO0wxanFvBL7GkM6dTHlgX+jhBApRetaWpnDabOeTcnA==} hasBin: true @@ -11068,6 +11207,12 @@ packages: resolution: {integrity: sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==} engines: {node: '>=0.10.0'} + /klaw/3.0.0: + resolution: {integrity: sha512-0Fo5oir+O9jnXu5EefYbVK+mHMBeEVEy2cmctR1O1NECcCkPRreJKrS6Qt/j3KC2C148Dfo9i3pCmCMsdqGr0g==} + dependencies: + graceful-fs: 4.2.10 + dev: true + /kleur/3.0.3: resolution: {integrity: sha512-eTIzlVOSUR+JxdDFepEYcBMtZ9Qqdef+rnzWdRZuMbOywu5tO2w2N7rqjoANZ5k9vywhL6Br1VRjUIgTQx4E8w==} engines: {node: '>=6'} @@ -11119,6 +11264,12 @@ packages: uhyphen: 0.1.0 dev: true + /linkify-it/3.0.3: + resolution: {integrity: sha512-ynTsyrFSdE5oZ/O9GEf00kPngmOfVwazR5GKDq6EYfhlpFug3J2zybX56a2PRRpc9P+FuSoGNAwjlbDs9jJBPQ==} + dependencies: + uc.micro: 1.0.6 + dev: true + /lit-element/3.2.2: resolution: {integrity: sha512-6ZgxBR9KNroqKb6+htkyBwD90XGRiqKDHVrW/Eh0EZ+l+iC+u+v+w3/BA5NGi4nizAVHGYvQBHUDuSmLjPp7NQ==} dependencies: @@ -11197,7 +11348,6 @@ packages: /lodash/4.17.21: resolution: {integrity: sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==} - dev: false /log-symbols/4.1.0: resolution: {integrity: sha512-8XPvpAA8uyhfteu8pIvQxpJZ7SYYdpUivZpGy6sFsBuKRY/7rQGavedeB8aK+Zkyq6upMFVL/9AW6vOYzfRyLg==} @@ -11302,10 +11452,37 @@ packages: engines: {node: '>=0.10.0'} dev: false + /markdown-it-anchor/8.6.6_2zb4u3vubltivolgu556vv4aom: + resolution: {integrity: sha512-jRW30YGywD2ESXDc+l17AiritL0uVaSnWsb26f+68qaW9zgbIIr1f4v2Nsvc0+s0Z2N3uX6t/yAw7BwCQ1wMsA==} + peerDependencies: + '@types/markdown-it': '*' + markdown-it: '*' + dependencies: + '@types/markdown-it': 12.2.3 + markdown-it: 12.3.2 + dev: true + + /markdown-it/12.3.2: + resolution: {integrity: sha512-TchMembfxfNVpHkbtriWltGWc+m3xszaRD0CZup7GFFhzIgQqxIfn3eGj1yZpfuflzPvfkt611B2Q/Bsk1YnGg==} + hasBin: true + dependencies: + argparse: 2.0.1 + entities: 2.1.0 + linkify-it: 3.0.3 + mdurl: 1.0.1 + uc.micro: 1.0.6 + dev: true + /markdown-table/3.0.3: resolution: {integrity: sha512-Z1NL3Tb1M9wH4XESsCDEksWoKTdlUafKc4pt0GRwjUyXaCFZ+dc3g2erqB6zm3szA2IUSi7VnPI+o/9jnxh9hw==} dev: false + /marked/4.2.12: + resolution: {integrity: sha512-yr8hSKa3Fv4D3jdZmtMMPghgVt6TWbk86WQaWhDloQjRSQhMMYCAro7jP7VDJrjjdV8pxVxMssXS8B8Y5DZ5aw==} + engines: {node: '>= 12'} + hasBin: true + dev: true + /matcher/3.0.0: resolution: {integrity: sha512-OkeDaAZ/bQCxeFAozM55PKcKU0yJMPGifLwV4Qgjitu+5MoAfSQN4lsLJeXZ1b8w0x+/Emda6MZgXS1jvsapng==} engines: {node: '>=10'} @@ -11500,6 +11677,10 @@ packages: unist-util-visit: 3.1.0 dev: true + /mdurl/1.0.1: + resolution: {integrity: sha512-/sKlQJCBYVY9Ers9hqzKou4H6V5UWc/M59TH2dvkt+84itfnq7uFOMLpOiOS4ujvHP4etln18fmIxA5R5fll0g==} + dev: true + /media-typer/0.3.0: resolution: {integrity: sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ==} engines: {node: '>= 0.6'} @@ -12018,6 +12199,10 @@ packages: engines: {node: '>=10'} hasBin: true + /mkdirp2/1.0.5: + resolution: {integrity: sha512-xOE9xbICroUDmG1ye2h4bZ8WBie9EGmACaco8K8cx6RlkJJrxGIqjGqztAI+NMhexXBcdGbSEzI6N3EJPevxZw==} + dev: true + /mocha/9.2.2: resolution: {integrity: sha512-L6XC3EdwT6YrIk0yXpavvLkn8h+EU+Y5UcCHKECyMbdUIxyMuZj4bX4U9e1nvnvUUvQVsV2VHQr5zLdcUkhW/g==} engines: {node: '>= 12.0.0'} @@ -12270,6 +12455,11 @@ packages: resolution: {integrity: sha512-NuAESUOUMrlIXOfHKzD6bpPu3tYt3xvjNdRIQ+FeT0lNb4K8WR70CaDxhuNguS2XG+GjkyMwOzsN5ZktImfhLA==} engines: {node: '>= 0.4'} + /object-to-spawn-args/2.0.1: + resolution: {integrity: sha512-6FuKFQ39cOID+BMZ3QaphcC8Y4cw6LXBLyIgPU+OhIYwviJamPAn+4mITapnSBQrejB+NNp+FMskhD8Cq+Ys3w==} + engines: {node: '>=8.0.0'} + dev: true + /object.assign/4.1.4: resolution: {integrity: sha512-1mxKf0e58bvyjSCtKYY4sRe9itRk3PJpquJOjeIkz885CczcI4IvJJDLPS72oowuSh+pBxUFROpX+TU++hxhZQ==} engines: {node: '>= 0.4'} @@ -13540,6 +13730,12 @@ packages: resolution: {integrity: sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg==} dev: true + /requizzle/0.2.4: + resolution: {integrity: sha512-JRrFk1D4OQ4SqovXOgdav+K8EAhSB/LJZqCz8tbX0KObcdeM15Ss59ozWMBWmmINMagCwmqn4ZNryUGpBsl6Jw==} + dependencies: + lodash: 4.17.21 + dev: true + /reselect/4.1.7: resolution: {integrity: sha512-Zu1xbUt3/OPwsXL46hvOOoQrap2azE7ZQbokq61BQfiXvhewsKDwhMeZjTX9sX0nvw1t/U5Audyn1I9P/m9z0A==} dev: false @@ -14101,12 +14297,24 @@ packages: resolution: {integrity: sha512-RwNA9Z/7PrK06rYLIzFMlaF+l73iwpzsqRIFgbMLbTcLD6cOao82TaWefPXQvB2fOC4AjuYSEndS7N/mTCbkdQ==} engines: {node: '>= 0.8'} + /stream-connect/1.0.2: + resolution: {integrity: sha512-68Kl+79cE0RGKemKkhxTSg8+6AGrqBt+cbZAXevg2iJ6Y3zX4JhA/sZeGzLpxW9cXhmqAcE7KnJCisUmIUfnFQ==} + engines: {node: '>=0.10.0'} + dependencies: + array-back: 1.0.4 + dev: true + /stream-transform/2.1.3: resolution: {integrity: sha512-9GHUiM5hMiCi6Y03jD2ARC1ettBXkQBoQAe7nJsPknnI0ow10aXjTnew8QtYQmLjzn974BnmWEAJgCY6ZP1DeQ==} dependencies: mixme: 0.5.4 dev: true + /stream-via/1.0.4: + resolution: {integrity: sha512-DBp0lSvX5G9KGRDTkR/R+a29H+Wk2xItOF+MpZLLNDWbEV9tGPnqLPxHEYjmiz8xGtJHRIqmI+hCjmNzqoA4nQ==} + engines: {node: '>=0.10.0'} + dev: true + /streamsearch/1.1.0: resolution: {integrity: sha512-Mcc5wHehp9aXz1ax6bZUyY5afg9u2rv5cqQI3mRrYkGC8rW2hM02jWuwjtL++LS5qinSyhj2QfLyNsuc+VsExg==} engines: {node: '>=10.0.0'} @@ -14389,6 +14597,10 @@ packages: engines: {node: '>=8'} dev: false + /temp-path/1.0.0: + resolution: {integrity: sha512-TvmyH7kC6ZVTYkqCODjJIbgvu0FKiwQpZ4D1aknE7xpcDf/qEOB8KZEK5ef2pfbVoiBhNWs3yx4y+ESMtNYmlg==} + dev: true + /tempy/0.6.0: resolution: {integrity: sha512-G13vtMYPT/J8A4X2SjdtBTphZlrp1gKv6hZiOjw14RCWg6GbHuQBGtjlx75xLbYV/wEc0D7G5K4rxKP/cXk8Bw==} engines: {node: '>=10'} @@ -14758,6 +14970,14 @@ packages: engines: {node: '>=4.2.0'} hasBin: true + /typical/2.6.1: + resolution: {integrity: sha512-ofhi8kjIje6npGozTip9Fr8iecmYfEbS06i0JnIg+rh51KakryWF4+jX8lLKZVhy6N+ID45WYSFCxPOdTWCzNg==} + dev: true + + /uc.micro/1.0.6: + resolution: {integrity: sha512-8Y75pvTYkLJW2hWQHXxoqRgV7qb9B+9vFEtidML+7koHUFapnVJAZ6cKs+Qjz5Aw3aZWHMC6u0wJE3At+nSGwA==} + dev: true + /uhyphen/0.1.0: resolution: {integrity: sha512-o0QVGuFg24FK765Qdd5kk0zU/U4dEsCtN/GSiwNI9i8xsSVtjIAOdTaVhLwZ1nrbWxFVMxNDDl+9fednsOMsBw==} dev: true @@ -14778,6 +14998,10 @@ packages: jiti: 1.16.2 dev: false + /underscore/1.13.6: + resolution: {integrity: sha512-+A5Sja4HP1M08MaXya7p5LvjuM7K6q/2EaC0+iovj/wOcMsTzMvDFbasi/oSapiwOlt252IqsKqPjCl7huKS0A==} + dev: true + /undici/5.14.0: resolution: {integrity: sha512-yJlHYw6yXPPsuOH0x2Ib1Km61vu4hLiRRQoafs+WUgX1vO64vgnxiCEN9dpIrhZyHFsai3F0AEj4P9zy19enEQ==} engines: {node: '>=12.18'} @@ -15371,6 +15595,11 @@ packages: '@vue/server-renderer': 3.2.45_vue@3.2.45 '@vue/shared': 3.2.45 + /walk-back/5.1.0: + resolution: {integrity: sha512-Uhxps5yZcVNbLEAnb+xaEEMdgTXl9qAQDzKYejG2AZ7qPwRQ81lozY9ECDbjLPNWm7YsO1IK5rsP1KoQzXAcGA==} + engines: {node: '>=12.17'} + dev: true + /wcwidth/1.0.1: resolution: {integrity: sha512-XHPEwS0q6TaxcvG85+8EYkbiCux2XtWG2mkc47Ng2A77BQu9+DqIOJldST4HgPkuea7dvKSj5VgX3P1d4rW8Tg==} dependencies: @@ -15714,6 +15943,10 @@ packages: engines: {node: '>=4.0'} dev: true + /xmlcreate/2.0.4: + resolution: {integrity: sha512-nquOebG4sngPmGPICTS5EnxqhKbCmz5Ox5hsszI2T6U5qdrJizBc+0ilYSEjTSzU0yZcmvppztXe/5Al5fUwdg==} + dev: true + /xregexp/2.0.0: resolution: {integrity: sha512-xl/50/Cf32VsGq/1R8jJE5ajH1yMCQkpmoS10QbFZWl2Oor4H0Me64Pu2yxvsRWK3m6soJbmGfzSR7BYmDcWAA==} dev: true diff --git a/scripts/docs/docgen.js b/scripts/docs/docgen.js new file mode 100644 index 000000000..5e7111c93 --- /dev/null +++ b/scripts/docs/docgen.js @@ -0,0 +1,100 @@ +import { slug as githubSlug } from 'github-slugger'; +import fs from 'fs'; +import path from 'path'; +import jsdoc from 'jsdoc-api'; + +// Fill this in to test a response locally, with fetching. +const STUB = fs.readFileSync('packages/astro/src/@types/astro.ts', {encoding: 'utf-8'}); +const VALID_CATEGORY = ['config', 'cliCommand', 'type']; +function processComment(comment) { + if (comment.kind === 'heading') { + return; + } + const cliFlag = comment.tags.find((f) => f.title === 'cli'); + const categoryFlag = comment.tags.find((f) => f.title === 'category'); + const typerawFlag = comment.tags.find((f) => f.title === 'typeraw'); + console.log(categoryFlag); + if (!comment.name) { + throw new Error(`Missing @docs JSDoc tag: @name`); + } + if (!comment.type && !typerawFlag) { + throw new Error(`Missing @docs JSDoc tag: @type or @typeraw`); + } + if (!categoryFlag) { + + } + // if (!VALID_CATEGORY.includes(categoryFlag.text)) { { + + // } + const typesFormatted = typerawFlag + ? typerawFlag.text.replace(/\{(.*)\}/, '$1') + : comment.type.names.join(' | '); + + return { + slug: githubSlug(comment.longname), + name: comment.longname, + description: comment.description && comment.description.trim(), + category: categoryFlag && categoryFlag.text, + type: typesFormatted, + cliFlag: cliFlag && cliFlag.text, + defaultValue: comment.defaultvalue, + version: comment.version, + seeAlsoLinks: comment.see, + } +} +/** + * The simple demo does not rely on the TypeScript compiler API; instead, it parses the + * source file directly. It uses the default parser configuration. + */ +export async function run() { + const inputBuffer = + STUB || + (await fetch( + 'https://raw.githubusercontent.com/withastro/astro/main/packages/astro/src/%40types/astro.ts' + ).then((r) => r.text())); + + // Get all `@docs` JSDoc comments in the file. + const allComments = [ + ...inputBuffer.matchAll(/\/\*\*\s*\n([^\*]|\*[^\/])*@docs([^\*]|\*[^\/])*\*\//g), + ]; + const allCommentsInput = allComments + .map((m) => m[0]) + .filter((c) => c.includes('* @docs')) + .join('\n\n'); + + console.log(jsdoc); + console.log(allCommentsInput); + console.log(jsdoc.explainSync({ source: allCommentsInput })); + + const allParsedComments = jsdoc + .explainSync({ source: allCommentsInput }) + .filter((data) => data.tags); + + let result = ``; + + for (const comment of allParsedComments) { + const proccessedCommentDoc = processComment(comment); + if (!proccessedCommentDoc) { + continue; + } + console.log(`packages/astro/reference/${proccessedCommentDoc.slug}.json`); + const savePath = `packages/astro/reference/${proccessedCommentDoc.slug}.json`; + fs.mkdirSync(path.dirname(savePath), { recursive: true }); + fs.writeFileSync( + savePath, + JSON.stringify(proccessedCommentDoc, undefined, 2), + 'utf8' + ); + } + + // result = result.replace(/https:\/\/docs\.astro\.build\//g, '/'); + + // console.log(result); + // fs.writeFileSync( + // 'src/pages/en/reference/configuration-reference.mdx', + // HEADER + result + FOOTER, + // 'utf8' + // ); +} + +run();