-
Notifications
You must be signed in to change notification settings - Fork 74
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update documentation to leverage new @internals/scripts (#1236)
* Add docs scripts
- Loading branch information
1 parent
b95bce8
commit a6d4d8c
Showing
49 changed files
with
2,587 additions
and
23 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| import path from 'path'; | ||
| import { DOCS_DIR, } from '@internals/common/constants'; | ||
| import { mkdirp } from '@internals/common/fs'; | ||
| import { writeAPIDocs } from './lib/write-api-docs.js'; | ||
| import { info, verbose } from '@internals/common/logger'; | ||
| import { getSharedArgs } from '../shared/get-shared-args.js'; | ||
| import { clearOutMarkdownFiles } from '../shared/clear-out-markdown-files.js'; | ||
|
|
||
| const EXAMPLES_DOCS_DEST = path.resolve(DOCS_DIR, 'docs/documentation/api'); | ||
|
|
||
| const writeAPIDocumentation = async ({ shouldClearMarkdown }: { shouldClearMarkdown: boolean }) => { | ||
| info('Writing API documentation'); | ||
| await mkdirp(EXAMPLES_DOCS_DEST); | ||
| if (shouldClearMarkdown) { | ||
| verbose(`Clearing out markdown files in ${EXAMPLES_DOCS_DEST}`) | ||
| await clearOutMarkdownFiles(EXAMPLES_DOCS_DEST); | ||
| } | ||
|
|
||
| return writeAPIDocs(EXAMPLES_DOCS_DEST); | ||
| }; | ||
|
|
||
|
|
||
| const main = async () => { | ||
| return writeAPIDocumentation(getSharedArgs()); | ||
| }; | ||
|
|
||
| main(); |
9 changes: 9 additions & 0 deletions
9
internals/scripts/src/bin/write/docs/api/lib/_templates/index.md.t
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| # API | ||
|
|
||
| API Documentation for UpscalerJS. | ||
|
|
||
| Available methods: | ||
|
|
||
| <% for (const method of methods) { %> | ||
| - [`<%- method.name %>`](./<%- method.name %>) | ||
| <% } %> |
1 change: 1 addition & 0 deletions
1
internals/scripts/src/bin/write/docs/api/lib/_templates/source.md.t
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| <small className="gray">Defined in <a target="_blank" href="<%- url %>"><%- prettyFileName %>:<%- line %></a></small> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,68 @@ | ||
| import { UPSCALER_DIR } from "@internals/common/constants"; | ||
| import path from 'path'; | ||
| import { DeclarationReflection, ReflectionKind, TypeParameterReflection } from "typedoc"; | ||
| import * as url from 'url'; | ||
| import { Definitions } from "./types.js"; | ||
| import { writePlatformSpecificDefinitions } from "./write-api-documentation-files/write-parameter.js"; | ||
|
|
||
| const __dirname = url.fileURLToPath(new URL('.', import.meta.url)); | ||
|
|
||
| export const REPO_ROOT = 'https://github.com/thekevinscott/UpscalerJS'; | ||
| export const UPSCALER_TSCONFIG_PATH = path.resolve(UPSCALER_DIR, 'tsconfig.esm.json'); | ||
| export const UPSCALER_SRC_PATH = path.resolve(UPSCALER_DIR, 'src'); | ||
| export const VALID_EXPORTS_FOR_WRITING_DOCS = ['default']; | ||
| export const VALID_METHODS_FOR_WRITING_DOCS = [ | ||
| 'constructor', | ||
| 'upscale', | ||
| 'execute', | ||
| 'warmup', | ||
| 'abort', | ||
| 'dispose', | ||
| 'getModel', | ||
| ]; | ||
| export const INTRINSIC_TYPES = [ | ||
| 'string', | ||
| 'number', | ||
| 'boolean', | ||
| ]; | ||
| export const TYPES_TO_EXPAND: Record<string, string[]> = { | ||
| 'upscale': ['Input', 'Progress'], | ||
| 'warmup': ['WarmupSizes'], | ||
| }; | ||
| export const TEMPLATES_DIR = path.resolve(__dirname, '_templates'); | ||
|
|
||
| export const makeNewExternalType = (name: string, _url: string): DeclarationReflection => { | ||
| const type = new DeclarationReflection(name, ReflectionKind['SomeType']); | ||
| type.sources = []; | ||
| return type; | ||
| }; | ||
|
|
||
| export const EXTERNALLY_DEFINED_TYPES: Record<string, DeclarationReflection> = { | ||
| 'AbortSignal': makeNewExternalType( | ||
| 'AbortSignal', | ||
| 'https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal' | ||
| ), | ||
| 'SerializableConstructor': makeNewExternalType( | ||
| 'SerializableConstructor', | ||
| 'https://github.com/tensorflow/tfjs/blob/38f8462fe642011ff1b7bcbb52e018f3451be58b/tfjs-core/src/serialization.ts#L54', | ||
| ), | ||
| } | ||
|
|
||
| export const EXPANDED_TYPE_CONTENT: Record<string, (definitions: Definitions, typeParameters: Record<string, TypeParameterReflection>) => string> = { | ||
| 'Input': (definitions) => writePlatformSpecificDefinitions(definitions), | ||
| 'WarmupSizes': () => ([ | ||
| '- `number` - a number representing both the size (width and height) of the patch.', | ||
| '- `{patchSize: number; padding?: number}` - an object with the `patchSize` and optional `padding` properties.', | ||
| '- `number[]` - an array of numbers representing the size (width and height) of the patch.', | ||
| '- `{patchSize: number; padding?: number}[]` - an array of objects with the `patchSize` and optional `padding` properties.', | ||
| ].join('\n')), | ||
| 'Progress': () => ([ | ||
| 'The progress callback function has the following four parameters:', | ||
| '- `progress` - a number between 0 and 1 representing the progress of the upscale.', | ||
| '- `slice` - a string or 3D tensor representing the current slice of the image being processed. The type returned is specified by the `progressOutput` option, or if not present, the `output` option, or if not present, string for the browser and tensor for node.', | ||
| '- `row` - the row of the image being processed.', | ||
| '- `col` - the column of the image being processed.', | ||
| '', | ||
| '[See the guide on progress for more information.](/documentation/guides/browser/usage/progress)', | ||
| ].join('\n')), | ||
| }; |
36 changes: 36 additions & 0 deletions
36
...cripts/src/bin/write/docs/api/lib/get-definitions/get-all-declaration-reflections.test.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| import { PlatformSpecificFileDeclarationReflection } from "../types.js"; | ||
| import { getAllDeclarationReflections } from "./get-all-declaration-reflections.js"; | ||
| import { getDeclarationReflectionsFromPackages } from "./get-declaration-reflections-from-packages.js"; | ||
| import { getTypesFromPlatformSpecificUpscalerFiles } from "./get-types-from-platform-specific-upscaler-files.js"; | ||
| import { DeclarationReflection } from "typedoc"; | ||
|
|
||
| vi.mock('./get-declaration-reflections-from-packages.js', () => ({ | ||
| getDeclarationReflectionsFromPackages: vi.fn(), | ||
| })); | ||
|
|
||
| vi.mock('./get-types-from-platform-specific-upscaler-files.js', () => ({ | ||
| getTypesFromPlatformSpecificUpscalerFiles: vi.fn(), | ||
| })); | ||
|
|
||
| describe('getAllDeclarationReflections()', () => { | ||
| afterEach(() => { | ||
| vi.clearAllMocks(); | ||
| }); | ||
| it('gets merged declaration reflections', async () => { | ||
| vi.mocked(getDeclarationReflectionsFromPackages).mockImplementation(() => { | ||
| return [ | ||
| 'foo', | ||
| ] as unknown as DeclarationReflection[]; | ||
| }); | ||
|
|
||
| vi.mocked(getTypesFromPlatformSpecificUpscalerFiles).mockImplementation(() => { | ||
| return Promise.resolve([ | ||
| 'bar', | ||
| ] as unknown as PlatformSpecificFileDeclarationReflection[]); | ||
| }); | ||
|
|
||
| const results = await getAllDeclarationReflections(); | ||
| expect(results).toEqual(['foo', 'bar']); | ||
|
|
||
| }); | ||
| }); |
16 changes: 16 additions & 0 deletions
16
...als/scripts/src/bin/write/docs/api/lib/get-definitions/get-all-declaration-reflections.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| import { UPSCALER_DIR } from "@internals/common/constants"; | ||
| import { UPSCALER_TSCONFIG_PATH } from "../constants.js"; | ||
| import { DeclarationReflection } from "typedoc"; | ||
| import { getDeclarationReflectionsFromPackages } from "./get-declaration-reflections-from-packages.js"; | ||
| import { getTypesFromPlatformSpecificUpscalerFiles } from "./get-types-from-platform-specific-upscaler-files.js"; | ||
| import { PlatformSpecificFileDeclarationReflection } from "../types.js"; | ||
|
|
||
| const DECLARATION_REFLECTION_FILE_DEFINITIONS = [{ | ||
| tsconfigPath: UPSCALER_TSCONFIG_PATH, | ||
| projectRoot: UPSCALER_DIR, | ||
| }]; | ||
|
|
||
| export const getAllDeclarationReflections = async (): Promise<(DeclarationReflection | PlatformSpecificFileDeclarationReflection)[]> => ([ | ||
| ...(await getTypesFromPlatformSpecificUpscalerFiles([{ fileName: 'image', typeName: 'Input' }])), | ||
| ...getDeclarationReflectionsFromPackages(DECLARATION_REFLECTION_FILE_DEFINITIONS), | ||
| ]); |
45 changes: 45 additions & 0 deletions
45
.../bin/write/docs/api/lib/get-definitions/get-declaration-reflections-from-packages.test.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| import { ProjectReflection } from "typedoc"; | ||
| import { getDeclarationReflectionsFromPackages } from "./get-declaration-reflections-from-packages.js"; | ||
| import { getPackageAsTree } from "./get-package-as-tree.js"; | ||
|
|
||
| vi.mock('./get-package-as-tree.js', () => { | ||
| return { | ||
| getPackageAsTree: vi.fn(), | ||
| } | ||
| }); | ||
|
|
||
| describe('getDeclarationReflectionsFromPackages', () => { | ||
| afterEach(() => { | ||
| vi.clearAllMocks(); | ||
| }); | ||
| it('returns an array of DeclarationReflections', () => { | ||
| vi.mocked(getPackageAsTree).mockImplementation(() => { | ||
| return { | ||
| children: [ | ||
| 'foo', | ||
| 'bar', | ||
| ], | ||
| } as unknown as ProjectReflection; | ||
| }); | ||
| expect(getDeclarationReflectionsFromPackages([ | ||
| { | ||
| tsconfigPath: 'tsconfig', | ||
| projectRoot: 'projectRoot', | ||
| }, | ||
| ])).toEqual(['foo', 'bar']); | ||
| }); | ||
|
|
||
| it('throws if receiving an empty children array', () => { | ||
| vi.mocked(getPackageAsTree).mockImplementation(() => { | ||
| return { | ||
| children: [], | ||
| } as unknown as ProjectReflection; | ||
| }); | ||
| expect(() => getDeclarationReflectionsFromPackages([ | ||
| { | ||
| tsconfigPath: 'tsconfig', | ||
| projectRoot: 'projectRoot', | ||
| }, | ||
| ])).toThrow(); | ||
| }); | ||
| }); |
22 changes: 22 additions & 0 deletions
22
...s/src/bin/write/docs/api/lib/get-definitions/get-declaration-reflections-from-packages.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| import { getPackageAsTree } from "./get-package-as-tree.js"; | ||
| import { DeclarationReflection } from "typedoc"; | ||
| import path from "path"; | ||
|
|
||
| export interface ProjectDefinition { | ||
| tsconfigPath: string; | ||
| projectRoot: string; | ||
| } | ||
|
|
||
| export const getDeclarationReflectionsFromPackages = (projectDefinitions: ProjectDefinition[]): DeclarationReflection[] => [ | ||
| ...projectDefinitions, | ||
| ].reduce<DeclarationReflection[]>((arr, { tsconfigPath, projectRoot }) => { | ||
| const { children } = getPackageAsTree( | ||
| path.join(projectRoot, 'src'), | ||
| tsconfigPath, | ||
| projectRoot, | ||
| ); | ||
| if (children === undefined || children.length === 0) { | ||
| throw new Error(`No children were found for ${projectRoot}. Indicates an error in the returned structure from getPackageAsTree`); | ||
| } | ||
| return arr.concat(children); | ||
| }, []); |
Oops, something went wrong.