aframe-schema-doc
Outputs documentation for the schemas (in Markdown format) for all calls to AFRAME.registerComponent and AFRAME.registerSystem.
We monkey patch calls to registerComponent() or registerSystem(), parse the schema and output a Markdown table with information from the schema. The documentation includes attribute name (converted to kebab-case), type, default value and description (obtained from a description property).
If using from Node the process works by simulating a browser environment with jsdom, loading AFRAME, and then loading the input file.
If using from the browser, the documentation is output to the console.
Examples
Given test.js
AFRAME.registerComponent("test", {
schema: {
alpha: {
type: "int",
description: "define the transparency of the subject (%)",
},
gammaEpsilon: {
default: "a",
oneOf: ["a", "b", "c"],
description: "defines the type of system to use",
},
beta: {
default: 10,
if: {gamma: ["a","c"]},
description: "the maximum intensity",
},
}
})aframe-schema-doc test.js
A-Frame Version: 0.8.2 (Date 2018-04-15, Commit #b20527f)
three Version: github:supermedium/three.js#r90fixMTLLoader
WebVR Polyfill Version: ^0.10.5
AFRAME version 0.8.2
Filename 'test.js' --> './test.js'
## Component test
| Property | Description | Default Value | Type |
| -------- | ----------- | ------------- | ---- |
|alpha|define the transparency of the subject (%)|0|int|
|beta|_if **gamma** is 'a' or 'c'_. the maximum intensity|10|number|
|gammaEpsilon|defines the type of system to use|'a'|['a', 'b', 'c']|
Copying into a Markdown file becomes
Component test
| Property | Description | Default Value | Type |
|---|---|---|---|
| alpha | define the transparency of the subject (%) | 0 | int |
| beta | if gamma is 'a' or 'c'. the maximum intensity | 10 | number |
| gammaEpsilon | defines the type of system to use | 'a' | ['a', 'b', 'c'] |
Installation
Using Node
npm install -g aframe-schema-doc
no installation needed, if using from the browser
Usage
If using Node
aframe-schema-doc <filename>
or from the browser, include the script after AFRAME, but before your script files. For example:
<head>
<script src="https://aframe.io/releases/0.8.2/aframe.min.js"></script>
<script src="https://unpkg.com/aframe-schema-doc/dist/aframe-schema-doc.js"></script>
<script src="YOUR .JS FILE HERE"></script>
<script> /* OR YOUR SCRIPT HERE */ </script>
</head>Configuration
| Switch | Description |
|---|---|
| --unsorted | output in the same order as the schema |
| --sorted | output in alphabetical order (default) |
| --kebabcase | output attribute names in kebab-case |
| --camelcase | output attribute names in camelCase (default) |
Limitations
If using Node, the application will try to load the file using require(), so if there are errors in the file that prevent it from executing then documentation will not be output.