awesomewm.d.tl/spec/scraper/module_doc_spec.tl

824 lines
28 KiB
Plaintext

local assert <const> = require("luassert")
local type Node = require("awesomewmdtl.types.Node")
local scraper <const> = require("awesomewmdtl.scraper.module_doc")
local get_doc_from_page = scraper.get_doc_from_page
local function test(html: string, module_path: string, expected_ast: Node, expected_other_nodes: { Node } | nil): function()
return function()
local ast <const>, other_nodes <const> = get_doc_from_page(html, module_path)
assert.same(expected_ast, ast)
assert.same(expected_other_nodes or {}, other_nodes)
end
end
describe("Scrap documentation", function()
it("should return a valid AST for an empty module", test(
"",
"empty",
{
children = {
{
children = {},
name = "Signal",
token = "enum",
}
},
name = "Empty",
module_path = "empty",
dependencies = {},
token = "module",
}))
it("should produce Variable and `property::` Signal nodes", test(
[[
<h2 class="section-header">
<a name="Object_properties"></a>Object properties
</h2>
<dl class="function">
<dt>
<a class="copy-link js-copy-link" name="value" href="#value">🔗</a>
<strong>value</strong>
<span class="proptype"><span class="summary_type">number</span></span>
<span class="baseclass"> · 1 signal </span>
</dt>
<dd>
<h3>Constraints:</h3>
<span class="property_type">
<table class="see_also">
<tbody><tr class="">
<td style="padding-left:0px;">
<i>
Default value
</i>
</td>
<td>: <code>0</code></td>
</tr><tr>
</tr><tr class="">
<td style="padding-left:0px;">
<i>
Negative allowed
</i>
</td>
<td>: true</td>
</tr><tr>
</tr></tbody></table>
</span>
</dd>
</dl>
]],
"property_signal",
{
children = {
{
children = {
{
name = "property::value",
token = "identifier",
},
},
name = "Signal",
token = "enum",
},
{
name = "value",
types = { "number" },
token = "variable",
}
},
name = "Property_signal",
module_path = "property_signal",
dependencies = {},
token = "module",
}))
it("should produce Enum nodes when an Object Property type is a String with constraints", test(
[[
<h2 class="section-header">
<a name="Object_properties"></a>Object properties
</h2>
<dl class="function">
<dt>
<a
class="copy-link js-copy-link"
name="horizontal_fit_policy"
href="#horizontal_fit_policy"
>🔗</a
>
<strong>horizontal_fit_policy</strong>
<span class="proptype"><span class="summary_type">string</span></span>
<span class="baseclass"> · 1 signal </span>
</dt>
<dd>
<span class="property_type">
<table class="see_also">
<tbody>
<tr class="">
<td style="padding-left: 0px">
<i> Default value </i>
</td>
<td>: <code>"auto"</code></td>
</tr>
<tr></tr>
<tr class="">
<td style="padding-left: 0px">
<i> Valid values: </i>
</td>
</tr>
<tr></tr>
<tr class="see_also_sublist">
<td style="padding-left: 15px">
<i>
<code>"auto"</code>
</i>
</td>
<td>
: Honor the <code>resize</code> variable and preserve the aspect
ratio.
</td>
</tr>
<tr></tr>
<tr class="see_also_sublist">
<td style="padding-left: 15px">
<i>
<code>"none"</code>
</i>
</td>
<td>: Do not resize at all.</td>
</tr>
<tr></tr>
<tr class="see_also_sublist">
<td style="padding-left: 15px">
<i>
<code>"fit"</code>
</i>
</td>
<td>: Resize to the widget width.</td>
</tr>
<tr></tr>
</tbody>
</table>
</span>
</dd>
</dl>
]],
"property_enum",
{
children = {
{
children = {
{
name = "property::horizontal_fit_policy",
token = "identifier",
},
},
name = "Signal",
token = "enum",
},
{
children = {
{
name = "auto",
token = "identifier",
},
{
name = "none",
token = "identifier",
},
{
name = "fit",
token = "identifier",
},
},
name = "Horizontal_fit_policy",
token = "enum",
},
{
name = "horizontal_fit_policy",
types = { "Horizontal_fit_policy" },
token = "variable",
},
},
name = "Property_enum",
module_path = "property_enum",
dependencies = {},
token = "module",
}))
it("should produce a `string` typed Variable node when a String Property has no constraint", test(
[[
<h2 class="section-header">
<a name="Object_properties"></a>Object properties
</h2>
<dl class="function">
<dt>
<a class="copy-link js-copy-link" name="markup" href="#markup">🔗</a>
<strong>markup</strong>
<span class="proptype"><span class="summary_type">string</span></span>
<span class="baseclass"> · 1 signal </span>
</dt>
<dd>
<span class="property_type">string</span>
</dd>
</dl>
]],
"property_string",
{
children = {
{
children = {
{
name = "property::markup",
token = "identifier",
},
},
name = "Signal",
token = "enum",
},
{
name = "markup",
types = { "string" },
token = "variable",
}
},
name = "Property_string",
module_path = "property_string",
dependencies = {},
token = "module",
}))
it("should provide a Function node with the `self` as the first positional parameter", test(
[[
<h2 class="section-header"><a name="Object_methods"></a>Object methods</h2>
<dl class="function">
<dt>
<a class="copy-link js-copy-link" name="swap" href="#swap">🔗</a>
<strong
>:swap <span class="function_args"> <b>(</b>tag2<b>)</b></span></strong
>
<span class="proptype"></span>
<span class="baseclass"> </span>
</dt>
<dd>
<h3>Parameters:</h3>
<table class="see_also">
<tbody>
<tr class="param_header">
<th>Name</th>
<th></th>
<th>Type(s)</th>
<th>Description</th>
</tr>
<tr>
<td><span class="parameter">tag2</span></td>
<td></td>
<td>
<span class="types"><span class="type">tag</span></span>
</td>
<td class="see_also_description">The second tag</td>
</tr>
</tbody>
</table>
</dd>
</dl>
]],
"awful.tag",
{
children = {
{
children = {},
name = "Signal",
token = "enum",
},
{
parameters = {
{
types = { "Tag" },
name = "self",
token = "variable",
},
{
types = { "tag" }, -- This needs to be fixed : tag -> Tag
name = "tag2",
token = "variable",
}
},
return_types = {},
name = "swap",
token = "function",
},
},
name = "Tag",
module_path = "awful.tag",
dependencies = {},
token = "module",
}))
it("should produce Signal nodes", test(
[[
<h2 class="section-header"><a name="Signals"></a>Signals</h2>
<dl class="function">
<dt>
<a
class="copy-link js-copy-link"
name="widget::layout_changed"
href="#widget::layout_changed"
>🔗</a
>
<strong>widget::layout_changed</strong>
<span class="baseclass"> ·&nbsp;Inherited from wibox.widget.base </span>
</dt>
<dd></dd>
<dt>
<a
class="copy-link js-copy-link"
name="widget::redraw_needed"
href="#widget::redraw_needed"
>🔗</a
>
<strong>widget::redraw_needed</strong>
<span class="baseclass"> ·&nbsp;Inherited from wibox.widget.base </span>
</dt>
<dd></dd>
</dl>
]],
"signal",
{
children = {
{
children = {
{
name = "widget::layout_changed",
token = "identifier",
},
{
name = "widget::redraw_needed",
token = "identifier",
},
},
name = "Signal",
token = "enum",
},
},
name = "Signal",
module_path = "signal",
dependencies = {},
token = "module",
}))
it("should produce Function nodes", test(
[[
<h2 class="section-header">
<a name="Static_module_functions"></a>Static module functions
</h2>
<dl class="function">
<dt>
<a class="copy-link js-copy-link" name="kill" href="#kill">🔗</a>
<strong
><span class="function_modname">awesome.</span>kill
<span class="function_args"> <b>(</b>pid, sig<b>)</b></span></strong
>
<span class="proptype"
><span class="summary_type"> -&gt;&nbsp;boolean</span></span
>
<span class="baseclass"> </span>
</dt>
<dd>
Send a signal to a process.
<h3>Parameters:</h3>
<table class="see_also">
<tbody>
<tr class="param_header">
<th>Name</th>
<th></th>
<th>Type(s)</th>
<th>Description</th>
</tr>
<tr>
<td><span class="parameter">pid</span></td>
<td></td>
<td>
<span class="types"><span class="type">integer</span></span>
</td>
<td class="see_also_description">
Process identifier. 0 and negative values have special meaning. See
<code>man 3 kill</code>.
</td>
</tr>
<tr>
<td><span class="parameter">sig</span></td>
<td></td>
<td>
<span class="types"><span class="type">integer</span></span>
</td>
<td class="see_also_description">
Signal number. See
<a href="../core_components/awesome.html#unix_signal"
>awesome.unix_signal</a
>
for a list of signals.
</td>
</tr>
</tbody>
</table>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">boolean</span></span>
true if the signal was successfully sent, else false
</ol>
</dd>
</dl>
]],
"awesome", -- The module name must be the same as the module name in the doc
{
children = {
{
children = {},
name = "Signal",
token = "enum",
},
{
parameters = {
{
types = { "integer" },
name = "pid",
token = "variable",
},
{
types = { "integer" },
name = "sig",
token = "variable",
},
},
return_types = { "boolean" },
name = "kill",
token = "function",
}
},
name = "Awesome",
module_path = "awesome",
dependencies = {},
token = "module",
}))
it("should produce a Record node when a function parameter is a named-parameter-table", test(
[[
<h2 class="section-header">
<a name="Static_module_functions"></a>Static module functions
</h2>
<dl class="function">
<dt>
<a
class="copy-link js-copy-link"
name="awful.screen.focused"
href="#awful.screen.focused"
>🔗</a
>
<strong
>awful.screen.focused
<span class="function_named_args"><b>{</b>[args]<b>}</b></span></strong
>
<span class="proptype"
><span class="summary_type"> -&gt;&nbsp;nil <i>or</i> screen</span></span
>
<span class="baseclass"> </span>
</dt>
<dd>
<h3>Parameters:</h3>
<table class="see_also">
<tbody>
<tr class="param_header">
<th>Name</th>
<th></th>
<th>Type(s)</th>
<th>Description</th>
<th>Default value</th>
</tr>
<tr>
<td><span class="parameter">args</span></td>
<td><span class="chips">Optional</span></td>
<td>
<span class="types"><span class="type">table</span></span>
</td>
<td class="see_also_description"></td>
<td><span class="not_applicable">Undefined</span></td>
</tr>
<tr class="see_also_sublist">
<td><span class="parameter">client</span></td>
<td><span class="chips">Optional</span></td>
<td>
<span class="types"><span class="type">boolean</span></span>
</td>
<td class="see_also_description">
Use the client screen instead of the mouse screen.
</td>
<td>
<span class="default_value"><code>false</code></span>
</td>
</tr>
<tr class="see_also_sublist">
<td><span class="parameter">mouse</span></td>
<td><span class="chips">Optional</span></td>
<td>
<span class="types"><span class="type">boolean</span></span>
</td>
<td class="see_also_description">Use the mouse screen</td>
<td>
<span class="default_value"><code>true</code></span>
</td>
</tr>
</tbody>
</table>
<h3>Returns:</h3>
<ol>
<span class="types"
>optional
<a class="type" href="../core_components/screen.html#screen"
>screen</a
></span
>
The focused screen object, or
<code>nil</code>
in case no screen is present currently.
</ol>
</dd>
</dl>
]],
"awful.screen",
{
children = {
{
children = {},
name = "Signal",
token = "enum",
},
{
children = {
{
types = { "boolean" },
name = "client",
token = "variable",
},
{
types = { "boolean" },
name = "mouse",
token = "variable",
}
},
name = "Focused_Args",
token = "record",
},
{
parameters = {
{
types = { "Focused_Args" },
name = "args",
token = "variable",
},
},
return_types = { "screen" },
name = "focused",
token = "function",
},
},
name = "Screen",
module_path = "awful.screen",
dependencies = {},
token = "module",
}))
it("should go back to a table typed parameter when the record is empty", test(
[[
<h2 class="section-header "><a name="Static_module_functions"></a>Static module functions</h2>
<dl class="function">
<dt>
<a class="copy-link js-copy-link" name="crush" href="#crush">🔗</a>
<strong><span class="function_modname">gears.table.</span>crush <span class="function_args"> <b>(</b>target, source, <span class="optional_param">raw</span><b>)</b></span></strong>
<span class="proptype"><span class="summary_type"> -&gt;&nbsp;table</span></span>
<span class="baseclass">
</span>
</dt>
<dd>
</p><h3>Parameters:</h3>
<table class="see_also">
<tbody><tr class="param_header">
<th>Name</th>
<th></th>
<th>Type(s)</th>
<th>Description</th>
<th>Default value</th>
</tr>
<tr>
<td><span class="parameter">target</span></td>
<td></td>
<td><span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.6" target="_blank">table</a></span></td>
<td class="see_also_description"> The target table. Values from <code>source</code> will be copied
into this table.</td>
<td><span class="not_applicable" title="This parameter is mandatory">Not applicable</span></td>
</tr>
<tr>
<td><span class="parameter">source</span></td>
<td></td>
<td><span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.6" target="_blank">table</a></span></td>
<td class="see_also_description"> The source table. Its values will be copied into
<code>target</code>.</td>
<td><span class="not_applicable" title="This parameter is mandatory">Not applicable</span></td>
</tr>
<tr>
<td><span class="parameter">raw</span></td>
<td><span class="chips">Optional</span></td>
<td><span class="types"><span class="type">bool</span></span></td>
<td class="see_also_description"> If <code>true</code>, values will be assigned with <a href="https://www.lua.org/manual/5.3/manual.html#pdf-rawset" target="_blank">rawset</a>.
This will bypass metamethods on <code>target</code>.</td>
<td><span class="default_value"><code>false</code></span></td>
</tr>
</tbody></table>
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="https://www.lua.org/manual/5.3/manual.html#6.6" target="_blank">table</a></span>
The target table.
</ol>
</dd>
</dl>
]],
"gears.table",
{
children = {
{
children = {},
name = "Signal",
token = "enum",
},
{
parameters = {
{
types = { "table" },
name = "target",
token = "variable",
},
{
types = { "table" },
name = "source",
token = "variable",
},
{
types = { "bool" },
name = "raw",
token = "variable",
}
},
return_types = { "table" },
name = "crush",
token = "function",
}
},
name = "Table",
module_path = "gears.table",
dependencies = {},
token = "module",
}))
it("should go back to a table typed parameter when the record is empty and it's the last parameter", test(
[[
<h2 class="section-header"><a name="Object_methods"></a>Object methods</h2>
<dl class="function">
<dt>
<a class="copy-link js-copy-link" name="tags" href="#tags">🔗</a>
<strong
>:tags
<span class="function_args"> <b>(</b>tags_table<b>)</b></span></strong
>
<span class="proptype"
><span class="summary_type"> -&gt;&nbsp;table</span></span
>
<span class="baseclass"> · 1 signal </span>
</dt>
<dd>
<h3>Parameters:</h3>
<table class="see_also">
<tbody>
<tr class="param_header">
<th>Name</th>
<th></th>
<th>Type(s)</th>
<th>Description</th>
</tr>
<tr>
<td><span class="parameter">tags_table</span></td>
<td></td>
<td>
<span class="types"
><a
class="type"
href="https://www.lua.org/manual/5.3/manual.html#6.6"
target="_blank"
>table</a
></span
>
</td>
<td class="see_also_description">
A table with tags to set, or <code>nil</code> to get the current
tags.
</td>
</tr>
</tbody>
</table>
<h3>Returns:</h3>
<ol>
<span class="types"
><a
class="type"
href="https://www.lua.org/manual/5.3/manual.html#6.6"
target="_blank"
>table</a
></span
>
A table with all tags.
</ol>
</dd>
</dl>
]],
"awful.client",
{
children = {
{
children = {},
name = "Signal",
token = "enum",
},
{
parameters = {
{
types = { "Client" },
name = "self",
token = "variable",
},
{
types = { "table" },
name = "tags_table",
token = "variable",
},
},
return_types = { "table" },
name = "tags",
token = "function",
},
},
name = "Client",
module_path = "awful.client",
dependencies = {},
token = "module",
}))
it("should return Function nodes with the `other_nodes` list when the function module name doesn't match the module name", test(
[[
<h2 class="section-header">
<a name="Static_module_functions"></a>Static module functions
</h2>
<dl class="function">
<dt>
<a class="copy-link js-copy-link" name="instances" href="#instances">🔗</a>
<strong
><span class="function_modname">client.</span>instances
<span class="function_args"> <b>(</b><b>)</b></span></strong
>
<span class="proptype"
><span class="summary_type"> -&gt;&nbsp;integer</span></span
>
<span class="baseclass"> </span>
</dt>
<dd>
Get the number of instances.
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">integer</span></span>
The number of client objects alive.
</ol>
<span id="item826" class="hide_extra"> </span>
</dd>
</dl>
]],
"awful.client",
{
children = {
{
children = {},
name = "Signal",
token = "enum",
},
},
name = "Client",
module_path = "awful.client",
dependencies = {},
token = "module",
},
{
{
parameters = {},
return_types = { "integer" },
name = "client.instances",
token = "function",
}
}))
end)