📝 refresh api docs (#1071)

graphql-markdown · Oct 31, 2023 · a5078ed · a5078ed
1 parent 311a2d0
commit a5078ed
Show file tree

Hide file tree

Showing 23 changed files with 739 additions and 562 deletions.
diff --git a/.github/workflows/smoke.yml b/.github/workflows/smoke.yml
@@ -19,9 +19,13 @@ concurrency:
 
 jobs:
   smoke:
-    name: Smoke Tests
+    name: Smoke Tests on Docusaurus ${{ matrix.docusaurus }}
     runs-on: ubuntu-latest
     if: github.event.pull_request.draft == false
+    strategy:
+      fail-fast: false
+      matrix:
+        docusaurus: [2]
     steps:
       - name: Install earthly
         uses: earthly/actions-setup@v1
@@ -30,19 +34,19 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Run Smoke Tests
-        run: earthly --ci github.com/graphql-markdown/graphql-markdown:${GITHUB_REF#refs/heads/}+smoke-test
+        run: earthly --ci --build-arg VERSION=${{ matrix.docusaurus }} github.com/graphql-markdown/graphql-markdown:${GITHUB_REF#refs/heads/}+smoke-test
         env:
           EARTHLY_NO_CACHE: true
 
       - name: Docusaurus Production Smoke Build without parameters and local schema
-        run: earthly --ci github.com/graphql-markdown/graphql-markdown:${GITHUB_REF#refs/heads/}+smoke-run
+        run: earthly --ci --build-arg VERSION=${{ matrix.docusaurus }} github.com/graphql-markdown/graphql-markdown:${GITHUB_REF#refs/heads/}+smoke-run
 
       - name: Docusaurus Production Smoke Build with parameters and remote schema
-        run: earthly --ci --build-arg OPTIONS="$OPTIONS" github.com/graphql-markdown/graphql-markdown:${GITHUB_REF#refs/heads/}+smoke-run
+        run: earthly --ci --build-arg OPTIONS="$OPTIONS" --build-arg VERSION=${{ matrix.docusaurus }} github.com/graphql-markdown/graphql-markdown:${GITHUB_REF#refs/heads/}+smoke-run
         env:
           OPTIONS: "--homepage data/anilist.md --schema https://graphql.anilist.co/ --force"
 
       - name: Docusaurus Production Smoke Build with groupByDirective option
-        run: earthly --ci --build-arg OPTIONS="$OPTIONS" github.com/graphql-markdown/graphql-markdown:${GITHUB_REF#refs/heads/}+smoke-run
+        run: earthly --ci --build-arg OPTIONS="$OPTIONS" --build-arg VERSION=${{ matrix.docusaurus }} github.com/graphql-markdown/graphql-markdown:${GITHUB_REF#refs/heads/}+smoke-run
         env:
           OPTIONS: "--homepage data/groups.md --schema data/schema_with_grouping.graphql --groupByDirective @doc(category|=Common) --base group-by --skip @noDoc"
diff --git a/Earthfile b/Earthfile
@@ -46,16 +46,18 @@ build-package:
   SAVE ARTIFACT graphql-markdown-$package.tgz
 
 build-docusaurus:
+  ARG VERSION=latest
   WORKDIR /
-  RUN npx --quiet create-docusaurus@latest docusaurus2 classic
+  RUN npx --quiet create-docusaurus@$VERSION docusaurus2 classic
   WORKDIR /docusaurus2
   RUN rm -rf docs; rm -rf blog; rm -rf src; rm -rf static/img
   RUN npm cache clean --force; rm -rf node_modules
   RUN npm ci
   RUN npm upgrade @docusaurus/core @docusaurus/preset-classic
 
 smoke-init:
-  FROM +build-docusaurus
+  ARG VERSION=latest
+  FROM +build-docusaurus --VERSION=$VERSION
   WORKDIR /docusaurus2
   RUN npm install graphql @graphql-tools/url-loader @graphql-tools/graphql-file-loader
   FOR package IN types utils graphql helpers logger printer-legacy diff core docusaurus
@@ -72,7 +74,8 @@ smoke-init:
   RUN node config-plugin.js
 
 smoke-test:
-  FROM +smoke-init
+  ARG VERSION=latest
+  FROM +smoke-init --VERSION=$VERSION
   WORKDIR /docusaurus2
   RUN npm config set update-notifier false
   RUN npm install -g jest 
@@ -84,16 +87,18 @@ smoke-test:
   RUN npx jest --runInBand
 
 smoke-run:
+  ARG VERSION=latest
   ARG OPTIONS=
-  FROM +smoke-init
+  FROM +smoke-init --VERSION=$VERSION
   WORKDIR /docusaurus2
   DO +GQLMD --options=$OPTIONS
   RUN npm run build
   RUN npm run clear
 
 build-examples:
+  ARG VERSION=latest
   ARG TARGET=examples
-  FROM +smoke-init
+  FROM +smoke-init --VERSION=$VERSION
   WORKDIR /docusaurus2
   RUN npm install prettier
   RUN mkdir $TARGET
@@ -104,8 +109,9 @@ build-examples:
   SAVE ARTIFACT ./$TARGET
 
 build-docs:
+  ARG VERSION=latest
   COPY ./website ./
-  COPY +build-examples/examples ./examples
+  COPY +build-examples/examples --VERSION=$VERSION ./examples
   COPY --dir docs .
   COPY --dir api .
   RUN npm install
@@ -114,7 +120,8 @@ build-docs:
   SAVE ARTIFACT --force ./build AS LOCAL build
 
 build-image:
-  FROM +build-docs
+  ARG VERSION=latest
+  FROM +build-docs --VERSION=$VERSION
   EXPOSE 8080
   ENTRYPOINT ["npm", "run", "serve", "--",  "--host=0.0.0.0", "--port=8080"]
   SAVE IMAGE graphql-markdown:docs

diff --git a/packages/graphql/docs/directive.md b/packages/graphql/docs/directive.md
@@ -1,4 +1,4 @@
-# Module: directive
+# directive
 
 Library supporting `customDirective` for directive based customization.
 
@@ -11,7 +11,7 @@ Library supporting `customDirective` for directive based customization.
 ### WILDCARD\_DIRECTIVE
 
 ```ts
-const WILDCARD_DIRECTIVE: ""
+const WILDCARD_DIRECTIVE: "*";
 ```
 
 Wildcard `*` character for matching any directive name.
@@ -24,30 +24,29 @@ See [getCustomDirectiveOptions](directive.md#getcustomdirectiveoptions), [isCust
 
 ## Functions
 
-### getConstDirectiveMap
+### getConstDirectiveMap()
 
 ```ts
-getConstDirectiveMap(entity, customDirectiveMap): Maybe< CustomDirectiveMap >
+getConstDirectiveMap(entity, customDirectiveMap): Maybe<CustomDirectiveMap>
 ```
 
 Returns a map of custom directives for a schema entity.
 
 #### Parameters
 
-| Parameter | Type | Description |
-| :------ | :------ | :------ |
-| `entity` | `unknown` | a GraphQL schema entity. |
-| `customDirectiveMap` | `Maybe`\< `CustomDirectiveMap` \> | a custom directive map (see [getCustomDirectives](directive.md#getcustomdirectives)). |
+▪ **entity**: `unknown`
 
-#### Returns
+a GraphQL schema entity.
 
-`Maybe`\< `CustomDirectiveMap` \>
+▪ **customDirectiveMap**: `Maybe`\<`CustomDirectiveMap`\>
 
-a map of GraphQL directives matching the custom directives defined, else `undefined`.
+a custom directive map (see [getCustomDirectives](directive.md#getcustomdirectives)).
 
-#### Source
+#### Returns
 
-[packages/graphql/src/directive.ts:247](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/directive.ts#L247)
+`Maybe`\<`CustomDirectiveMap`\>
+
+a map of GraphQL directives matching the custom directives defined, else `undefined`.
 
 #### Example
 
@@ -98,32 +97,35 @@ const map = getConstDirectiveMap(schema.getType("Test"), customDirectives);
 
 ```
 
+#### Source
+
+[packages/graphql/src/directive.ts:247](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/directive.ts#L247)
+
 ***
 
-### getCustomDirectiveOptions
+### getCustomDirectiveOptions()
 
 ```ts
-getCustomDirectiveOptions(schemaDirectiveName, customDirectiveOptions): Maybe< CustomDirectiveOptions >
+getCustomDirectiveOptions(schemaDirectiveName, customDirectiveOptions): Maybe<CustomDirectiveOptions>
 ```
 
 Returns a record set of custom handlers from a directive by name.
 
 #### Parameters
 
-| Parameter | Type | Description |
-| :------ | :------ | :------ |
-| `schemaDirectiveName` | `DirectiveName` | the GraphQL directive name. |
-| `customDirectiveOptions` | `CustomDirective` | the `customDirective` option. |
+▪ **schemaDirectiveName**: `DirectiveName`
 
-#### Returns
+the GraphQL directive name.
 
-`Maybe`\< `CustomDirectiveOptions` \>
+▪ **customDirectiveOptions**: `CustomDirective`
 
-a record set of custom handlers for the matching directive (or if `*` is declared), or undefined if no match.
+the `customDirective` option.
 
-#### Source
+#### Returns
 
-[packages/graphql/src/directive.ts:76](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/directive.ts#L76)
+`Maybe`\<`CustomDirectiveOptions`\>
+
+a record set of custom handlers for the matching directive (or if `*` is declared), or undefined if no match.
 
 #### Example
 
@@ -144,32 +146,35 @@ const customDirectives = getCustomDirectiveOptions("testB", customDirectiveOptio
 // }
 ```
 
+#### Source
+
+[packages/graphql/src/directive.ts:76](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/directive.ts#L76)
+
 ***
 
-### getCustomDirectives
+### getCustomDirectives()
 
 ```ts
-getCustomDirectives(schemaMap, customDirectiveOptions?): Maybe< CustomDirectiveMap >
+getCustomDirectives(schemaMap, customDirectiveOptions?): Maybe<CustomDirectiveMap>
 ```
 
 Returns a custom directives map with custom handlers from `customDirective`.
 
 #### Parameters
 
-| Parameter | Type | Description |
-| :------ | :------ | :------ |
-| `schemaMap` | `Pick`\< `SchemaMap`, `"directives"` \> | the GraphQL schema map returned by [introspection!getSchemaMap](introspection.md#getschemamap) |
-| `customDirectiveOptions`? | `CustomDirective` | the `customDirective` option. |
+▪ **schemaMap**: `Pick`\<`SchemaMap`, `"directives"`\>
 
-#### Returns
+the GraphQL schema map returned by [introspection!getSchemaMap](introspection.md#getschemamap)
 
-`Maybe`\< `CustomDirectiveMap` \>
+▪ **customDirectiveOptions?**: `CustomDirective`
 
-a custom directive map, or undefined if no match.
+the `customDirective` option.
 
-#### Source
+#### Returns
 
-[packages/graphql/src/directive.ts:150](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/directive.ts#L150)
+`Maybe`\<`CustomDirectiveMap`\>
+
+a custom directive map, or undefined if no match.
 
 #### Example
 
@@ -222,9 +227,13 @@ const customDirectives = getCustomDirectives(schemaMap, customDirectiveOptions);
 // }
 ```
 
+#### Source
+
+[packages/graphql/src/directive.ts:150](https://github.com/graphql-markdown/graphql-markdown/blob/main/packages/graphql/src/directive.ts#L150)
+
 ***
 
-### isCustomDirective
+### isCustomDirective()
 
 ```ts
 isCustomDirective(schemaDirectiveName, customDirectiveOptions): boolean
@@ -234,10 +243,13 @@ Checks if a directive name is referenced in `customDirective` option.
 
 #### Parameters
 
-| Parameter | Type | Description |
-| :------ | :------ | :------ |
-| `schemaDirectiveName` | `DirectiveName` | the GraphQL directive name. |
-| `customDirectiveOptions` | `CustomDirective` | the `customDirective` option. |
+▪ **schemaDirectiveName**: `DirectiveName`
+
+the GraphQL directive name.
+
+▪ **customDirectiveOptions**: `CustomDirective`
+
+the `customDirective` option.
 
 #### Returns
 

diff --git a/packages/graphql/docs/formatter.md b/packages/graphql/docs/formatter.md
@@ -1,35 +1,39 @@
-# Module: formatter
+# formatter
 
 Internal library of helpers for formatting GraphQL values.
 
 ## Functions
 
-### getFormattedDefaultValue
+### getFormattedDefaultValue()
 
 ```ts
-getFormattedDefaultValue<T>(entity): Maybe< string | T >
+getFormattedDefaultValue<T>(entity): Maybe<string | T>
 ```
 
 Returns a printable formatted value for a GraphQL type.
 This is the generic function.
 
 #### Type parameters
 
-| Parameter |
-| :------ |
-| `T` |
+▪ **T**
 
 #### Parameters
 
-| Parameter | Type | Description |
-| :------ | :------ | :------ |
-| `entity` | `object` | the GraphQL schema entity processed. |
-| `entity.defaultValue` | `T` | the GraphQL schema type's value to be formatted. |
-| `entity.type` | `Maybe`\< `GraphQLType` \> | the GraphQL schema type. |
+▪ **entity**: `object`
+
+the GraphQL schema entity processed.
+
+▪ **entity.defaultValue**: `T`
+
+the GraphQL schema type's value to be formatted.
+
+▪ **entity.type**: `Maybe`\<`GraphQLType`\>
+
+the GraphQL schema type.
 
 #### Returns
 
-`Maybe`\< `string` \| `T` \>
+`Maybe`\<`string` \| `T`\>
 
 a printable formatted value.