Module:Documentation: Difference between revisions
Jump to navigation
Jump to search
metawikimedia>Tacsipacsi don’t preprocess the result—everything should already have been preprocessed by that point, and the yet another preprocessing makes the section edit links point to this module instead of the respective documentation subpage |
MeowyCats2 (talk | contribs) m 224 revisions imported |
||
(18 intermediate revisions by 13 users not shown) | |||
Line 3: | Line 3: | ||
-- Get required modules. | -- Get required modules. | ||
local getArgs = require('Module:Arguments').getArgs | local getArgs = require('Module:Arguments').getArgs | ||
-- Get the config table. | -- Get the config table. | ||
local cfg = mw.loadData('Module:Documentation/config') | local cfg = mw.loadData('Module:Documentation/config') | ||
local p = {} | local p = {} | ||
Line 33: | Line 32: | ||
expectType = expectType or 'string' | expectType = expectType or 'string' | ||
if type(msg) ~= expectType then | if type(msg) ~= expectType then | ||
error | error('message: type error in message cfg.' .. cfgKey .. ' (' .. expectType .. ' expected, got ' .. type(msg) .. ')', 2) | ||
end | end | ||
if not valArray then | if not valArray then | ||
Line 41: | Line 40: | ||
local function getMessageVal(match) | local function getMessageVal(match) | ||
match = tonumber(match) | match = tonumber(match) | ||
return valArray[match] or error | return valArray[match] or error('message: no value found for key $' .. match .. ' in message cfg.' .. cfgKey, 4) | ||
end | end | ||
return ugsub(msg, '$([1-9][0-9]*)', getMessageVal) | |||
end | end | ||
Line 82: | Line 80: | ||
ret[#ret + 1] = select(i, ...) | ret[#ret + 1] = select(i, ...) | ||
end | end | ||
return '< | -- 'documentation-toolbar' | ||
return '<span class="' .. message('toolbar-class') .. '">(' | |||
.. table.concat(ret, ' | ') .. ')</span>' | |||
end | end | ||
Line 112: | Line 112: | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
-- | -- Entry points | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
p. | function p.nonexistent(frame) | ||
if mw.title.getCurrentTitle().subpageText == 'testcases' then | |||
return frame:expandTemplate{title = 'module test cases notice'} | |||
else | |||
return p.main(frame) | |||
end | |||
end | end | ||
p.main = makeInvokeFunc('_main') | |||
function p._main(args) | function p._main(args) | ||
Line 129: | Line 129: | ||
-- This function defines logic flow for the module. | -- This function defines logic flow for the module. | ||
-- @args - table of arguments passed by the user | -- @args - table of arguments passed by the user | ||
--]] | --]] | ||
local env = p.getEnvironment(args) | local env = p.getEnvironment(args) | ||
local root = mw.html.create() | local root = mw.html.create() | ||
root | root | ||
:tag('div') | :tag('div') | ||
:attr(' | -- 'documentation-container' | ||
:addClass(message('main-div- | :addClass(message('container')) | ||
:attr('role', 'complementary') | |||
:wikitext(p. | :attr('aria-labelledby', args.heading ~= '' and 'documentation-heading' or nil) | ||
:attr('aria-label', args.heading == '' and 'Documentation' or nil) | |||
:newline() | |||
:tag('div') | |||
-- 'documentation' | |||
:addClass(message('main-div-classes')) | |||
:newline() | |||
:wikitext(p._startBox(args, env)) | |||
:wikitext(p._content(args, env)) | |||
:tag('div') | |||
-- 'documentation-clear' | |||
:addClass(message('clear')) | |||
:done() | |||
:newline() | |||
:done() | |||
:wikitext(p._endBox(args, env)) | |||
:done() | :done() | ||
:wikitext(p.addTrackingCategories(env)) | :wikitext(p.addTrackingCategories(env)) | ||
return tostring(root) | -- 'Module:Documentation/styles.css' | ||
return mw.getCurrentFrame():extensionTag ( | |||
'templatestyles', '', {src=cfg['templatestyles'] | |||
}) .. tostring(root) | |||
end | end | ||
Line 158: | Line 167: | ||
function p.getEnvironment(args) | function p.getEnvironment(args) | ||
--[[ | --[[ | ||
-- Returns a table with information about the environment, including title objects and other namespace- or | -- Returns a table with information about the environment, including title | ||
-- objects and other namespace- or path-related data. | |||
-- @args - table of arguments passed by the user | -- @args - table of arguments passed by the user | ||
-- | -- | ||
Line 168: | Line 177: | ||
-- env.sandboxTitle - the /sandbox subpage. | -- env.sandboxTitle - the /sandbox subpage. | ||
-- env.testcasesTitle - the /testcases subpage. | -- env.testcasesTitle - the /testcases subpage. | ||
-- | -- | ||
-- Data includes: | -- Data includes: | ||
-- env.subjectSpace - the number of the title's subject namespace. | -- env.subjectSpace - the number of the title's subject namespace. | ||
-- env.docSpace - the number of the namespace the title puts its documentation in. | -- env.docSpace - the number of the namespace the title puts its documentation in. | ||
Line 262: | Line 269: | ||
--]] | --]] | ||
return mw.title.new(env.docpageBase .. '/' .. message('testcases-subpage')) | return mw.title.new(env.docpageBase .. '/' .. message('testcases-subpage')) | ||
end | end | ||
function envFuncs.subjectSpace() | function envFuncs.subjectSpace() | ||
Line 284: | Line 278: | ||
function envFuncs.docSpace() | function envFuncs.docSpace() | ||
-- The documentation namespace number. For most namespaces this is | -- The documentation namespace number. For most namespaces this is the | ||
-- subject namespace. However, pages in the Article, File, | -- same as the subject namespace. However, pages in the Article, File, | ||
-- namespaces must have their /doc, /sandbox and /testcases pages in talk space. | -- MediaWiki or Category namespaces must have their /doc, /sandbox and | ||
-- /testcases pages in talk space. | |||
local subjectSpace = env.subjectSpace | local subjectSpace = env.subjectSpace | ||
if subjectSpace == 0 or subjectSpace == 6 or subjectSpace == 8 or subjectSpace == 14 then | if subjectSpace == 0 or subjectSpace == 6 or subjectSpace == 8 or subjectSpace == 14 then | ||
Line 312: | Line 307: | ||
local compareUrl = mw.uri.fullUrl( | local compareUrl = mw.uri.fullUrl( | ||
'Special:ComparePages', | 'Special:ComparePages', | ||
{page1 = templateTitle.prefixedText, page2 = sandboxTitle.prefixedText} | { page1 = templateTitle.prefixedText, page2 = sandboxTitle.prefixedText} | ||
) | ) | ||
return tostring(compareUrl) | return tostring(compareUrl) | ||
Line 322: | Line 317: | ||
return env | return env | ||
end | end | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
Line 448: | Line 337: | ||
local links | local links | ||
local content = args.content | local content = args.content | ||
if not content then | if not content or args[1] then | ||
-- No need to include the links if the documentation is on the template page itself. | -- No need to include the links if the documentation is on the template page itself. | ||
local linksData = p.makeStartBoxLinksData(args, env) | local linksData = p.makeStartBoxLinksData(args, env) | ||
Line 476: | Line 365: | ||
-- 'history-link-display' --> 'history' | -- 'history-link-display' --> 'history' | ||
-- 'purge-link-display' --> 'purge' | -- 'purge-link-display' --> 'purge' | ||
-- 'module-preload' --> 'Template:Documentation/preload-module-doc' | -- 'module-preload' --> 'Template:Documentation/preload-module-doc' | ||
-- 'docpage-preload' --> 'Template:Documentation/preload' | -- 'docpage-preload' --> 'Template:Documentation/preload' | ||
Line 495: | Line 383: | ||
data.docTitle = docTitle | data.docTitle = docTitle | ||
-- View, display, edit, and purge links if /doc exists. | -- View, display, edit, and purge links if /doc exists. | ||
data.viewLinkDisplay = | data.viewLinkDisplay = message('view-link-display') | ||
data.editLinkDisplay = | data.editLinkDisplay = message('edit-link-display') | ||
data.historyLinkDisplay = | data.historyLinkDisplay = message('history-link-display') | ||
data.purgeLinkDisplay = | data.purgeLinkDisplay = message('purge-link-display') | ||
-- Create link if /doc doesn't exist. | -- Create link if /doc doesn't exist. | ||
local preload = args.preload | local preload = args.preload | ||
if not preload then | if not preload then | ||
if | if subjectSpace == 828 then -- Module namespace | ||
preload = message('module-preload') | preload = message('module-preload') | ||
else | else | ||
Line 511: | Line 397: | ||
end | end | ||
data.preload = preload | data.preload = preload | ||
data.createLinkDisplay = | data.createLinkDisplay = message('create-link-display') | ||
return data | return data | ||
end | end | ||
Line 517: | Line 403: | ||
function p.renderStartBoxLinks(data) | function p.renderStartBoxLinks(data) | ||
--[[ | --[[ | ||
-- Generates the [view][edit][history][purge] or [create] links from the data table. | -- Generates the [view][edit][history][purge] or [create][purge] links from the data table. | ||
-- @data - a table of data generated by p.makeStartBoxLinksData | -- @data - a table of data generated by p.makeStartBoxLinksData | ||
--]] | --]] | ||
Line 523: | Line 409: | ||
local function escapeBrackets(s) | local function escapeBrackets(s) | ||
-- Escapes square brackets with HTML entities. | -- Escapes square brackets with HTML entities. | ||
s = s:gsub('%[', '[') -- Replace square brackets with HTML entities. | |||
s = s:gsub('%]', ']') | |||
return s | return s | ||
end | end | ||
Line 531: | Line 417: | ||
local docTitle = data.docTitle | local docTitle = data.docTitle | ||
local title = data.title | local title = data.title | ||
local purgeLink = makeUrlLink(title:fullUrl{action = 'purge'}, data.purgeLinkDisplay) | |||
if docTitle.exists then | if docTitle.exists then | ||
local viewLink = makeWikilink(docTitle.prefixedText, data.viewLinkDisplay) | local viewLink = makeWikilink(docTitle.prefixedText, data.viewLinkDisplay) | ||
local editLink = makeUrlLink(docTitle:fullUrl{action = 'edit'}, data.editLinkDisplay) | local editLink = makeUrlLink(docTitle:fullUrl{action = 'edit'}, data.editLinkDisplay) | ||
local historyLink = makeUrlLink(docTitle:fullUrl{action = 'history'}, data.historyLinkDisplay) | local historyLink = makeUrlLink(docTitle:fullUrl{action = 'history'}, data.historyLinkDisplay) | ||
ret = '[%s] [%s] [%s] [%s]' | ret = '[%s] [%s] [%s] [%s]' | ||
ret = escapeBrackets(ret) | ret = escapeBrackets(ret) | ||
Line 541: | Line 427: | ||
else | else | ||
local createLink = makeUrlLink(docTitle:fullUrl{action = 'edit', preload = data.preload}, data.createLinkDisplay) | local createLink = makeUrlLink(docTitle:fullUrl{action = 'edit', preload = data.preload}, data.createLinkDisplay) | ||
ret = '[%s]' | ret = '[%s] [%s]' | ||
ret = escapeBrackets(ret) | ret = escapeBrackets(ret) | ||
ret = mw.ustring.format(ret, createLink) | ret = mw.ustring.format(ret, createLink, purgeLink) | ||
end | end | ||
return ret | return ret | ||
Line 556: | Line 442: | ||
-- | -- | ||
-- Messages: | -- Messages: | ||
-- 'documentation-icon-wikitext' --> '[[File:Test Template Info-Icon - Version (2).svg|50px|link=|alt= | -- 'documentation-icon-wikitext' --> '[[File:Test Template Info-Icon - Version (2).svg|50px|link=|alt=]]' | ||
-- 'template-namespace-heading' --> 'Template documentation' | -- 'template-namespace-heading' --> 'Template documentation' | ||
-- 'module-namespace-heading' --> 'Module documentation' | -- 'module-namespace-heading' --> 'Module documentation' | ||
-- 'file-namespace-heading' --> 'Summary' | -- 'file-namespace-heading' --> 'Summary' | ||
-- 'other-namespaces-heading' --> 'Documentation' | -- 'other-namespaces-heading' --> 'Documentation' | ||
-- 'testcases-create-link-display' --> 'create' | -- 'testcases-create-link-display' --> 'create' | ||
--]=] | --]=] | ||
Line 582: | Line 466: | ||
data.heading = heading | data.heading = heading | ||
elseif subjectSpace == 10 then -- Template namespace | elseif subjectSpace == 10 then -- Template namespace | ||
data.heading = | data.heading = message('documentation-icon-wikitext') .. ' ' .. message('template-namespace-heading') | ||
elseif subjectSpace == 828 then -- Module namespace | elseif subjectSpace == 828 then -- Module namespace | ||
data.heading = | data.heading = message('documentation-icon-wikitext') .. ' ' .. message('module-namespace-heading') | ||
elseif subjectSpace == 6 then -- File namespace | elseif subjectSpace == 6 then -- File namespace | ||
data.heading = | data.heading = message('file-namespace-heading') | ||
else | |||
data.heading = message('other-namespaces-heading') | |||
end | |||
-- Heading CSS | |||
local headingStyle = args['heading-style'] | |||
if headingStyle then | |||
data.headingStyleText = headingStyle | |||
else | else | ||
data. | -- 'documentation-heading' | ||
data.headingClass = message('main-div-heading-class') | |||
end | end | ||
-- Data for the [view][edit][history][purge] or [create] links. | -- Data for the [view][edit][history][purge] or [create] links. | ||
if links then | if links then | ||
-- 'mw-editsection-like plainlinks' | |||
data. | data.linksClass = message('start-box-link-classes') | ||
data.links = links | data.links = links | ||
end | end | ||
Line 606: | Line 499: | ||
local sbox = mw.html.create('div') | local sbox = mw.html.create('div') | ||
sbox | sbox | ||
:addClass(message(' | -- 'documentation-startbox' | ||
:tag(' | :addClass(message('start-box-class')) | ||
:addClass( | :newline() | ||
:tag('span') | |||
:addClass(data.headingClass) | |||
:attr('id', 'documentation-heading') | |||
:cssText(data.headingStyleText) | |||
:wikitext(data.heading) | :wikitext(data.heading) | ||
local links = data.links | local links = data.links | ||
if links then | if links then | ||
sbox | sbox:tag('span') | ||
:addClass(data.linksClass) | |||
:attr('id', data.linksId) | |||
:wikitext(links) | |||
end | end | ||
return tostring(sbox) | return tostring(sbox) | ||
Line 635: | Line 531: | ||
local content = args.content | local content = args.content | ||
if not content and docTitle and docTitle.exists then | if not content and docTitle and docTitle.exists then | ||
content = args._content or mw.getCurrentFrame():expandTemplate{title = docTitle} | content = args._content or mw.getCurrentFrame():expandTemplate{title = docTitle.prefixedText} | ||
end | |||
if mw.site.siteName == "Miraheze Developers Wiki" and args.noexportinstructions ~= "yes" then | |||
local export = mw.getCurrentFrame():expandTemplate{title="How to export"} | |||
content = export .. "<br/>" .. (content or '') | |||
end | end | ||
-- The line breaks below are necessary so that "=== Headings ===" at the start and end | -- The line breaks below are necessary so that "=== Headings ===" at the start and end | ||
-- of docs are interpreted correctly. | -- of docs are interpreted correctly. | ||
return '\n' .. (content or '') .. '\n' | |||
end | end | ||
Line 669: | Line 565: | ||
-- @args - a table of arguments passed by the user | -- @args - a table of arguments passed by the user | ||
-- @env - environment table containing title objects, etc., generated with p.getEnvironment | -- @env - environment table containing title objects, etc., generated with p.getEnvironment | ||
-- | |||
--]=] | --]=] | ||
Line 694: | Line 591: | ||
end | end | ||
-- Assemble the | -- Assemble the link box. | ||
local text = '' | local text = '' | ||
if linkBox then | if linkBox then | ||
Line 704: | Line 601: | ||
-- Add sandbox and testcases links. | -- Add sandbox and testcases links. | ||
-- "Editors can experiment in this template's sandbox and testcases pages." | -- "Editors can experiment in this template's sandbox and testcases pages." | ||
text = text .. (p.makeExperimentBlurb(args, env) or '') | text = text .. (p.makeExperimentBlurb(args, env) or '') .. '<br />' | ||
if not args.content and not args[1] then | if not args.content and not args[1] then | ||
-- "Please add categories to the /doc subpage." | -- "Please add categories to the /doc subpage." | ||
Line 713: | Line 609: | ||
end | end | ||
text = text .. ' ' .. (p.makeSubpagesBlurb(args, env) or '') --"Subpages of this template" | text = text .. ' ' .. (p.makeSubpagesBlurb(args, env) or '') --"Subpages of this template" | ||
end | end | ||
end | end | ||
local box = mw.html.create('div') | |||
-- 'documentation-metadata' | |||
box:attr('role', 'note') | |||
:addClass(message('end-box-class')) | |||
-- 'plainlinks' | |||
:addClass(message('end-box-plainlinks')) | |||
:wikitext(text) | |||
:done() | |||
return '\n' .. tostring(box) | |||
end | end | ||
Line 737: | Line 634: | ||
-- 'history-link-display' --> 'history' | -- 'history-link-display' --> 'history' | ||
-- 'transcluded-from-blurb' --> | -- 'transcluded-from-blurb' --> | ||
-- 'The above [[ | -- 'The above [[Wikipedia:Template documentation|documentation]] | ||
-- is [[ | -- is [[Help:Transclusion|transcluded]] from $1.' | ||
-- 'module-preload' --> 'Template:Documentation/preload-module-doc' | -- 'module-preload' --> 'Template:Documentation/preload-module-doc' | ||
-- 'create-link-display' --> 'create' | -- 'create-link-display' --> 'create' | ||
-- 'create-module-doc-blurb' --> | -- 'create-module-doc-blurb' --> | ||
-- 'You might want to $1 a documentation page for this [[ | -- 'You might want to $1 a documentation page for this [[Wikipedia:Lua|Scribunto module]].' | ||
--]=] | --]=] | ||
local docTitle = env.docTitle | local docTitle = env.docTitle | ||
if not docTitle | if not docTitle then | ||
return nil | return nil | ||
end | end | ||
Line 753: | Line 650: | ||
local docLink = makeWikilink(docTitle.prefixedText) | local docLink = makeWikilink(docTitle.prefixedText) | ||
local editUrl = docTitle:fullUrl{action = 'edit'} | local editUrl = docTitle:fullUrl{action = 'edit'} | ||
local editDisplay = | local editDisplay = message('edit-link-display') | ||
local editLink = makeUrlLink(editUrl, editDisplay) | local editLink = makeUrlLink(editUrl, editDisplay) | ||
local historyUrl = docTitle:fullUrl{action = 'history'} | local historyUrl = docTitle:fullUrl{action = 'history'} | ||
local historyDisplay = | local historyDisplay = message('history-link-display') | ||
local historyLink = makeUrlLink(historyUrl, historyDisplay) | local historyLink = makeUrlLink(historyUrl, historyDisplay) | ||
ret = message('transcluded-from-blurb', {docLink}) | ret = message('transcluded-from-blurb', {docLink}) | ||
Line 765: | Line 662: | ||
-- /doc does not exist; ask to create it. | -- /doc does not exist; ask to create it. | ||
local createUrl = docTitle:fullUrl{action = 'edit', preload = message('module-preload')} | local createUrl = docTitle:fullUrl{action = 'edit', preload = message('module-preload')} | ||
local createDisplay = | local createDisplay = message('create-link-display') | ||
local createLink = makeUrlLink(createUrl, createDisplay) | local createLink = makeUrlLink(createUrl, createDisplay) | ||
ret = message('create-module-doc-blurb', {createLink}) | ret = message('create-module-doc-blurb', {createLink}) | ||
Line 838: | Line 735: | ||
local mirrorPreload = message('mirror-link-preload') | local mirrorPreload = message('mirror-link-preload') | ||
local mirrorUrl = sandboxTitle:fullUrl{action = 'edit', preload = mirrorPreload, summary = mirrorSummary} | local mirrorUrl = sandboxTitle:fullUrl{action = 'edit', preload = mirrorPreload, summary = mirrorSummary} | ||
if subjectSpace == 828 then | |||
mirrorUrl = sandboxTitle:fullUrl{action = 'edit', preload = templateTitle.prefixedText, summary = mirrorSummary} | |||
end | |||
local mirrorDisplay = message('mirror-link-display') | local mirrorDisplay = message('mirror-link-display') | ||
local mirrorLink = makeUrlLink(mirrorUrl, mirrorDisplay) | local mirrorLink = makeUrlLink(mirrorUrl, mirrorDisplay) | ||
Line 849: | Line 749: | ||
local testcasesEditDisplay = message('testcases-edit-link-display') | local testcasesEditDisplay = message('testcases-edit-link-display') | ||
local testcasesEditLink = makeUrlLink(testcasesEditUrl, testcasesEditDisplay) | local testcasesEditLink = makeUrlLink(testcasesEditUrl, testcasesEditDisplay) | ||
testcasesLinks = testcasesLink .. ' ' .. makeToolbar(testcasesEditLink) | -- for Modules, add testcases run link if exists | ||
if testcasesTitle.contentModel == "Scribunto" and testcasesTitle.talkPageTitle and testcasesTitle.talkPageTitle.exists then | |||
local testcasesRunLinkDisplay = message('testcases-run-link-display') | |||
local testcasesRunLink = makeWikilink(testcasesTitle.talkPageTitle.prefixedText, testcasesRunLinkDisplay) | |||
testcasesLinks = testcasesLink .. ' ' .. makeToolbar(testcasesEditLink, testcasesRunLink) | |||
else | |||
testcasesLinks = testcasesLink .. ' ' .. makeToolbar(testcasesEditLink) | |||
end | |||
else | else | ||
local testcasesPreload | local testcasesPreload | ||
Line 918: | Line 825: | ||
) | ) | ||
return message('subpages-blurb', {subpagesLink}) | return message('subpages-blurb', {subpagesLink}) | ||
end | end | ||