from pathlib import Path
from docs.__generator__.utils import (
convert_blockquote_admonitions,
generate_badge_svg,
get_package_info,
get_plugin_description,
get_value_by_path,
get_values_by_path,
jsdoc_to_inline_markdown,
jsdoc_to_markdown,
plugin_name_to_camel_case,
)
PARAMETER_TYPE_MAPPING = {
"KEYS": "array of strings",
"BOOL": "boolean",
"STRING": "string",
"INT": "numeric",
"FLOAT": "numeric",
"FUNCTION": "function",
"KEY": "string",
"KEYS": "array of strings",
# "SELECT": "",
"HTML_STRING": "HTML string",
"IMAGE": "image file",
"AUDIO": "audio file",
"VIDEO": "video file",
# "OBJECT": "",
# "COMPLEX": "",
# "TIMELINE": "",
}
def generate_plugin_parameters_section(plugin_dir: Path):
description = get_plugin_description(plugin_dir)
output = """
## Parameters
In addition to the [parameters available in all
plugins](../overview/plugins.md#parameters-available-in-all-plugins), this plugin
accepts the following parameters. Parameters with a default value of undefined must be
specified. Other parameters can be left unspecified if the default value is acceptable.
| Parameter | Type | Default Value | Description |
| --------- | ---- | ------------- | ----------- |
"""
for parameter in get_values_by_path(
description,
"$.children[?name = default].children[?name = info].type.declaration.children[?name = parameters].type.declaration.children[?kindString = Property]",
):
parameter_name = parameter["name"]
parameter_type = get_value_by_path(
parameter, "$.type.declaration.children[?name = type].type.name"
)
if parameter_type in PARAMETER_TYPE_MAPPING:
parameter_type = PARAMETER_TYPE_MAPPING[parameter_type]
is_array = get_value_by_path(
parameter, "$.type.declaration.children[?name = array].type.value"
)
if is_array:
parameter_type = f"array of {parameter_type}s"
default_value_description = get_value_by_path(
parameter, "$.type.declaration.children[?name = default]"
)
# If `default_value` has a TSDoc summary, display it as the default value
default_value_summary = get_value_by_path(
default_value_description, "$.comment.summary"
) or get_value_by_path(
default_value_description,
"$.type.declaration.signatures[0].comment.summary",
)
if default_value_summary:
default_value = jsdoc_to_inline_markdown(default_value_summary)
else:
default_value = get_value_by_path(
default_value_description, "$.defaultValue"
)
# Large arrays are not displayed by default, so assembling a custom string
# here
if is_array and default_value == "...":
default_array_values = get_values_by_path(
default_value_description, "$.type.target.elements[*].value"
)
if default_array_values:
separator = '", "'
default_value = f'["{separator.join(default_array_values)}"]'
is_required = default_value == "undefined"
required_marker = "*" if is_required else ""
if is_required:
default_value = ""
description = jsdoc_to_inline_markdown(
get_values_by_path(parameter, "$.comment.summary[*]")
)
output += f"{parameter_name}{required_marker} | {parameter_type} | {default_value} | {description} \n"
return output
def generate_plugin_summary(plugin_dir: Path):
summary = get_value_by_path(
get_plugin_description(plugin_dir),
"$.children[?name = default].comment.summary",
)
return convert_blockquote_admonitions(jsdoc_to_markdown(summary))
def generate_plugin_version_info(plugin_dir: Path):
info = get_package_info(plugin_dir)
return f"[{generate_badge_svg('Current version',info['version'])}](https://github.com/jspsych/jsPsych/blob/main/{plugin_dir}/CHANGELOG.md)"
def generate_plugin_author_info(plugin_dir: Path):
author = get_value_by_path(
get_plugin_description(plugin_dir),
"$.children[?name = default].comment.blockTags[?tag = @author].content[0].text",
)
return generate_badge_svg("Author", author, "lightgray")
def generate_plugin_installation_section(plugin_dir: Path):
info = get_package_info(plugin_dir)
plugin_dir_name = plugin_dir.name
return f"""
## Install
Using the CDN-hosted JavaScript file:
```js
```
Using the JavaScript file downloaded from a GitHub release dist archive:
```js
```
Using NPM:
```
npm install {info["name"]}
```
```js
import {plugin_name_to_camel_case(plugin_dir_name)} from '{info["name"]}';
```
"""