@ui-js/grok
v1.8.0
Published
A tool to build beautiful documentation from TypeScript declaration files
Downloads
224
Readme
Grok
grok: /grok/, /grohk/, vt.
To understand. Connotes intimate and exhaustive knowledge.
Grok turns a TypeScript declaration file into a beautiful, readable, web page.
Installation
npm install --global @ui-js/grokUsage
# Create documentation for the .d.ts files in ./dist into the ./docs folder
grok ./dist --outDir docsConfiguration
Configuration can be specified:
- as a
grokproperty inpackage.json - as a
grok.config.json,grok.config.yaml,grok.config.jsfile in your project - or as a specific file using the
--configCLI option. In that case, the config file will be used in addition to other configuration files that may be present (it doesn't replace them)
The configuration can include the following keys:
sdkNameThe name of the SDK being documentedexcludeAn array of glob patterns to skip documenting, e.g.'**/*.test.ts'cssVariablesA dictionary of variables and their associated value which will be attached to the<body>tag.tutorialPathPrefix added to the value of a{@tutorial}tag to determine the URL to redirected to.For example,
{@tutorial readme.html}withtutorialPath = 'https://example.com/docs'will redirect to 'https://example.com/docs/readme.html'externalReferences: Set of symbols that have an external reference other than the standard one (MDN).Can be used for global symbols, or symbols referenced cross-module.
modulesAn array of module names that will be documented. This is useful both to indicate the order in which the modules should be displayed in the documentation and to 'hide' any unnecessary modules, while still preserving their visibility to the parser.documentTemplateA string or function which will be used to build the output file. If a string, the following substitutions will be applied:{{content}}HTML markup of the documentation (suitable for as the content of a<body>tag){{sdkName}}The name of the SDK, as indicated above{{packageName}}{{moduleName}}The name of the module being documented, if there is a single one{{className}}The name of the first class being documented{{directoryName}}The name of the directory being documented
If a function, the function is passed an object literal with the following properties:
content,sdkName,packageNameandcssVariableswhich is the dictionary specified in the options.
Tags
Grok supports the standard tags defined by tsdoc.
The {@link symbol} and its variants can use the tsdoc
standard declaration references
to disambiguate which symbol to point to.
Grok supports a few additional extensions, including:
- `{@tutorial path | name} to create links to pages with more detailed discussions
{@linkcode symbol}and[[`symbol` | title]]to create a link to a symbold displayed as code (in monospace font)[[symbol]]a synonym for{@link symbol}@keywordsfollowed by a comma separated list of words which can be used by the search box
export type InlineShortcutsOptions = {
/** @deprecated Use:
* ```typescript
* mf.setConfig(
* 'inlineShortcuts',
* { ...mf.getConfig('inlineShortcuts'),
* ...newShortcuts
* }
* )
* ```
* to add `newShortcuts` to the default ones. See {@linkcode setConfig} */
overrideDefaultInlineShortcuts?: boolean;
};/**
* Converts a LaTeX string to an Abstract Syntax Tree (MathJSON)
*
* **See:** {@tutorial MATHJSON | MathJson}
*
* @param latex A string of valid LaTeX. It does not have to start
* with a mode token such as a `$$` or `\(`.
* @param options.macros A dictionary of LaTeX macros
*
* @return The Abstract Syntax Tree as an object literal using the MathJSON format.
* @category Converting
* @keywords convert, latex, mathjson, ast
*/
export declare function latexToAST(
latex: string,
options?: {
macros?: MacroDictionary;
}
);