Module:ST/Usage

Documentation

[purge]

This sub-module generates documentation for templates that use Module:ST—see Module:ST#Implementation for more information. As a side effect, it also adds templates to Category:ST Templates. The sub-module is defined separately from its parent module in order to reduce code complexity and parsing/loading times—it should only be loaded and executed once per template page, not every time the template itself is used.

The above documentation is transcluded from Module:ST/Usage/doc. (edit | history)

---

--
-- Define example argument patterns
--

local icon = {
	{
		"Just the icon.",
		{}
	},
	{
		"Icon with name and link.",
		{"-"}
	},
	{
		"The icon may be enlarged.",
		{"-", size="large", name="A Large Icon"}
	},
	{
		"Name, link, and alt text may all be overridden.",
		{"-", link="Heroes", name="Custom Name", alt="Custom Alt"}
	},
	{
		"The link may also be disabled.",
		{"-", link="", name="Link Disabled"}
	},
}

local icon_fallback = {
	{
		"Formatted text.",
		{"123.456"}
	},
}


--
-- Group together argument patterns by type and generate corresponding
-- documentation for each pattern
--

local usages_by_type = {
	icon={icon, icon_fallback},
}

local function render_template_code(id, args)
	local kw_args, pos_args = {}, {}
	for k, v in pairs(args) do
		if type(k) == "number" then
			table.insert(pos_args, "|" .. v)
		else
			table.insert(kw_args, ("|%s=%s"):format(k, v))
		end
	end
	return ("<code>{{%s%s%s}}</code>"):format(id,
		table.concat(pos_args), table.concat(kw_args))
end

local msg = "''This template and its corresponding documentation were " ..
"automatically generated. See [[Module:ST]] for more details. " ..
"[[Category:ST Templates]]''"

local function generate(frame)
	local id = mw.title.getCurrentTitle().text

	local res = mw.html.create()

	local usage_table = res:tag("table"):addClass("wikitable")
	local header = usage_table:tag("tr")
	header:tag("th"):wikitext("Code")
	header:tag("th"):wikitext("Appearance")
	header:tag("th"):wikitext("Description")

	for _, usages in ipairs(usages_by_type[frame.args.type]) do
		for _, usage in ipairs(usages) do
			local row = usage_table:tag("tr")
			local desc, args = unpack(usage)
			row:tag("td"):wikitext(
				render_template_code(id, args))
			row:tag("td"):wikitext(
				frame:expandTemplate{title=id, args=args})
			row:tag("td"):wikitext(desc)
		end
	end

	res:wikitext(msg)

	return res
end

return {generate=generate}