Module:Documentation
From Shroudforge
More actions
Documentation for this module may be created at Module:Documentation/doc
require('strict')
--- @module Documentation
--- The documentation header on module and template pages and on their /doc
--- subpages, followed by the Technical details panel. Template:Documentation
--- invokes doc() at the top of each /doc page.
-- <nowiki>
local button = require('Module:ButtonLua')
local hatnote = require('Module:Hatnote')._hatnote
local icon = require('Module:Icon')
local yesno = require('Module:Yesno')
local p = {}
local NS_TEMPLATE = 10
local NS_MODULE = 828
local REPO_URL = 'https://github.com/StarCitizenTools/wiki-tools/tree/main/pages/'
local WIKIPEDIA_URL = 'https://en.wikipedia.org/wiki/'
local ICONS = {
page = 'CdxIconBook.svg',
edit = 'CdxIconEdit.svg',
history = 'CdxIconHistory.svg',
purge = 'CdxIconReload.svg',
back = 'CdxIconArrowPrevious.svg',
}
--- @param value string|nil a {{Documentation}} flag such as `git=`
--- @return boolean
local function isOn(value)
return yesno(value) == true
end
--- The visible text of a wikitext link, for the panel's plain-text facts.
--- @param wikitext string
--- @return string
local function linkText(wikitext)
return wikitext:match('^%s*%[%[[^|%]]*|(.-)%]%]%s*$')
or wikitext:match('^%s*%[%[(.-)%]%]%s*$')
or wikitext:match('^%s*%[%S+%s+(.-)%]%s*$')
or wikitext
end
--- Where the page was imported from, as a wikitext link: `importedFrom=`, or
--- its `fromWikipedia=` shorthand for the same title on the English Wikipedia.
--- @param args table the {{Documentation}} arguments
--- @param page string the documented page
--- @return string|nil
local function importOrigin(args, page)
if args.importedFrom and args.importedFrom ~= '' then
return args.importedFrom
end
if isOn(args.fromWikipedia) then
return '[' .. WIKIPEDIA_URL .. mw.uri.encode(page, 'WIKI') .. ' Wikipedia]'
end
return nil
end
--- The Source row lines of the Technical details panel: where the page is
--- maintained (`git=`) and where it came from.
--- @param args table the {{Documentation}} arguments
--- @param kind string 'module' or 'template'
--- @param rootText string
--- @param page string the documented page
--- @return table[] DependenciesSource[]
local function sources(args, kind, rootText, page)
local list = {}
if isOn(args.git) then
local url = REPO_URL .. kind .. '/' .. mw.uri.encode(rootText, 'PATH')
list[#list + 1] = { label = 'wiki-tools', text = 'Synced with [' .. url .. ' wiki-tools] on GitHub' }
end
local origin = importOrigin(args, page)
if origin then
-- The label goes in the panel's <summary>, which must hold no link: a bare URL would autolink.
list[#list + 1] = { label = 'from ' .. mw.text.nowiki(linkText(origin)), text = 'Imported from ' .. origin }
end
return list
end
--- @param kind string 'module' or 'template'
--- @param onDoc boolean the render is the /doc subpage itself
--- @param baseText string the /doc page's base page name, its sort key
--- @param imported boolean
--- @return string
local function categories(kind, onDoc, baseText, imported)
local plural = kind == 'module' and 'Modules' or 'Templates'
if onDoc then
return '[[Category:' .. plural .. ' documentation|' .. baseText .. ']]'
end
local out = {}
if kind == 'module' then
out[#out + 1] = '[[Category:Modules]]'
end
if imported then
out[#out + 1] = '[[Category:Imported ' .. plural:lower() .. ']]'
end
return table.concat(out)
end
--- A quiet icon-only header button. ButtonLua names it with aria-label; the
--- wrapper is what the phone layout stretches.
--- @param props table ButtonProps: label, icon and link
--- @return string
local function action(props)
props.weight = 'quiet'
props.iconOnly = true
return tostring(mw.html.create('span'):addClass('t-documentation__action'):wikitext(button.render(props)))
end
--- @param title string
--- @param subtitle string wikitext
--- @param actions string[]
--- @return string
local function header(title, subtitle, actions)
local root = mw.html.create('div'):addClass('t-documentation__header')
root:tag('span')
:addClass('t-documentation__icon')
:wikitext(icon.render({ icon = ICONS.page, mask = true, size = '1.125rem' }))
local heading = root:tag('div'):addClass('t-documentation__heading')
heading
:tag('div')
:addClass('t-documentation__title')
:attr('role', 'heading')
:attr('aria-level', '2')
:wikitext(title)
heading:tag('div'):addClass('t-documentation__subtitle'):wikitext(subtitle)
root:tag('div'):addClass('t-documentation__actions'):wikitext(table.concat(actions))
return tostring(root)
end
--- A failure in Module:Dependencies, or a module it requires, must not break
--- every documentation page: require and render it inside a pcall.
--- @param options table DependenciesPanelOptions
--- @return string
local function technicalDetails(options)
local ok, result = pcall(function()
return require('Module:Dependencies').panel(options)
end)
if ok then
return result
end
return '<strong class="error">' .. mw.text.nowiki(tostring(result)) .. '</strong>'
end
--- `{{#invoke:Documentation|doc}}`, from Template:Documentation.
--- @param frame table
--- @return string
function p.doc(frame)
local title = mw.title.getCurrentTitle()
local args = frame:getParent().args
local page = args[1]
if page == nil or page == '' then
page = title.fullText:gsub('/[Dd]o[ck]u?$', '')
end
local kind = title.namespace == NS_MODULE and 'module' or 'template'
local onDoc = title.subpageText == 'doc'
-- Left open on purpose: {{Documentation}} sits at the top of the /doc page,
-- and the wrapper holds the rest of it until the parser closes it at the end.
local out = { '<div class="t-documentation' .. (isOn(args.git) and ' t-documentation--git' or '') .. '">' }
out[#out + 1] = frame:extensionTag({ name = 'templatestyles', args = { src = 'Module:Icon/styles.css' } })
out[#out + 1] = frame:extensionTag({ name = 'templatestyles', args = { src = 'Module:Documentation/styles.css' } })
if onDoc then
out[#out + 1] = header('Documentation subpage', 'Shown on [[' .. page .. ']]', {
action({ label = 'Back to the ' .. kind, icon = ICONS.back, link = page }),
})
else
local doc = page .. '/doc'
out[#out + 1] =
header(kind == 'module' and 'Module documentation' or 'Template documentation', 'From [[' .. doc .. ']]', {
action({ label = 'Edit', icon = ICONS.edit, link = 'Special:EditPage/' .. doc }),
action({ label = 'History', icon = ICONS.history, link = 'Special:PageHistory/' .. doc }),
action({ label = 'Purge', icon = ICONS.purge, link = 'Special:Purge/' .. title.fullText }),
})
end
local notices = mw.html.create('div'):addClass('t-documentation__notices')
if not onDoc and title.namespace == NS_MODULE and title.subpageText == 'testcases' then
notices:wikitext(
hatnote(
'This is the test cases page for the module [[Module:' .. title.baseText .. ']].',
{ icon = 'WikimediaUI-LabFlask.svg' }
)
)
end
notices:wikitext(technicalDetails({
addCategories = (not onDoc) and args.category or nil,
sources = sources(args, kind, title.rootText, page),
}))
out[#out + 1] = tostring(notices)
if title.namespace == NS_TEMPLATE or title.namespace == NS_MODULE then
out[#out + 1] = categories(kind, onDoc, title.baseText, importOrigin(args, page) ~= nil)
end
if not onDoc and title.namespace == NS_MODULE then
local testcases = title.text .. '/testcases'
if mw.title.new(testcases, 'Module').exists then
out[#out + 1] = frame:preprocess('{{#invoke:' .. testcases .. '|run}}')
end
end
return table.concat(out)
end
-- Test-only exports. Not part of the public API.
p._internal = {
categories = categories,
linkText = linkText,
sources = sources,
}
return p
-- </nowiki>