Difference between revisions of "Module:Documentation"
no edit summary
| Line 1: | Line 1: | ||
-- This module implements {{documentation}}. | -- This module implements {{documentation}}. | ||
-- Get required modules. | -- Get required modules. | ||
local getArgs = require('Module:Arguments').getArgs | local getArgs = require('Module:Arguments').getArgs | ||
local htmlBuilder = require('Module:HtmlBuilder') | local htmlBuilder = require('Module:HtmlBuilder') | ||
local messageBox = require('Module:Message box') | local messageBox = require('Module:Message box') | ||
-- 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 = {} | ||
-- Often-used functions. | -- Often-used functions. | ||
local ugsub = mw.ustring.gsub | local ugsub = mw.ustring.gsub | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
-- Helper functions | -- Helper functions | ||
| Line 20: | Line 20: | ||
-- table for testing purposes. | -- table for testing purposes. | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
local function message(cfgKey, valArray, expectType) | local function message(cfgKey, valArray, expectType) | ||
--[[ | --[[ | ||
| Line 39: | Line 39: | ||
return msg | return msg | ||
end | end | ||
local function getMessageVal(match) | local function getMessageVal(match) | ||
match = tonumber(match) | match = tonumber(match) | ||
return valArray[match] or error('message: no value found for key $' .. match .. ' in message cfg.' .. cfgKey, 4) | return valArray[match] or error('message: no value found for key $' .. match .. ' in message cfg.' .. cfgKey, 4) | ||
end | end | ||
local ret = ugsub(msg, '$([1-9][0-9]*)', getMessageVal) | local ret = ugsub(msg, '$([1-9][0-9]*)', getMessageVal) | ||
return ret | return ret | ||
end | end | ||
p.message = message | p.message = message | ||
local function makeWikilink(page, display) | local function makeWikilink(page, display) | ||
if display then | if display then | ||
| Line 58: | Line 58: | ||
end | end | ||
end | end | ||
p.makeWikilink = makeWikilink | p.makeWikilink = makeWikilink | ||
local function makeCategoryLink(cat, sort) | local function makeCategoryLink(cat, sort) | ||
local catns = mw.site.namespaces[14].name | local catns = mw.site.namespaces[14].name | ||
return makeWikilink(catns .. ':' .. cat, sort) | return makeWikilink(catns .. ':' .. cat, sort) | ||
end | end | ||
p.makeCategoryLink = makeCategoryLink | p.makeCategoryLink = makeCategoryLink | ||
local function makeUrlLink(url, display) | local function makeUrlLink(url, display) | ||
return mw.ustring.format('[%s %s]', url, display) | return mw.ustring.format('[%s %s]', url, display) | ||
end | end | ||
p.makeUrlLink = makeUrlLink | p.makeUrlLink = makeUrlLink | ||
local function makeToolbar(...) | local function makeToolbar(...) | ||
local ret = {} | local ret = {} | ||
| Line 85: | Line 85: | ||
return '<small style="font-style: normal;">(' .. table.concat(ret, ' | ') .. ')</small>' | return '<small style="font-style: normal;">(' .. table.concat(ret, ' | ') .. ')</small>' | ||
end | end | ||
p.makeToolbar = makeToolbar | p.makeToolbar = makeToolbar | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
-- Argument processing | -- Argument processing | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
local function makeInvokeFunc(funcName) | local function makeInvokeFunc(funcName) | ||
return function (frame) | return function (frame) | ||
| Line 111: | Line 111: | ||
end | end | ||
end | end | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
-- Main function | -- Main function | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
p.main = makeInvokeFunc('_main') | p.main = makeInvokeFunc('_main') | ||
function p._main(args) | function p._main(args) | ||
--[[ | --[[ | ||
| Line 150: | Line 150: | ||
return tostring(root) | return tostring(root) | ||
end | end | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
-- Environment settings | -- Environment settings | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
function p.getEnvironment(args) | function p.getEnvironment(args) | ||
--[[ | --[[ | ||
| Line 179: | Line 179: | ||
-- returned will be nil. | -- returned will be nil. | ||
--]] | --]] | ||
local env, envFuncs = {}, {} | local env, envFuncs = {}, {} | ||
-- Set up the metatable. If triggered we call the corresponding function in the envFuncs table. The value | -- Set up the metatable. If triggered we call the corresponding function in the envFuncs table. The value | ||
-- returned by that function is memoized in the env table so that we don't call any of the functions | -- returned by that function is memoized in the env table so that we don't call any of the functions | ||
| Line 198: | Line 198: | ||
end | end | ||
}) | }) | ||
function envFuncs.title() | function envFuncs.title() | ||
-- The title object for the current page, or a test page passed with args.page. | -- The title object for the current page, or a test page passed with args.page. | ||
| Line 210: | Line 210: | ||
return title | return title | ||
end | end | ||
function envFuncs.templateTitle() | function envFuncs.templateTitle() | ||
--[[ | --[[ | ||
| Line 227: | Line 227: | ||
end | end | ||
end | end | ||
function envFuncs.docTitle() | function envFuncs.docTitle() | ||
--[[ | --[[ | ||
| Line 244: | Line 244: | ||
return mw.title.new(docpage) | return mw.title.new(docpage) | ||
end | end | ||
function envFuncs.sandboxTitle() | function envFuncs.sandboxTitle() | ||
--[[ | --[[ | ||
| Line 253: | Line 253: | ||
return mw.title.new(env.docpageBase .. '/' .. message('sandbox-subpage')) | return mw.title.new(env.docpageBase .. '/' .. message('sandbox-subpage')) | ||
end | end | ||
function envFuncs.testcasesTitle() | function envFuncs.testcasesTitle() | ||
--[[ | --[[ | ||
| Line 262: | Line 262: | ||
return mw.title.new(env.docpageBase .. '/' .. message('testcases-subpage')) | return mw.title.new(env.docpageBase .. '/' .. message('testcases-subpage')) | ||
end | end | ||
function envFuncs.printTitle() | function envFuncs.printTitle() | ||
--[[ | --[[ | ||
| Line 271: | Line 271: | ||
return env.templateTitle:subPageTitle(message('print-subpage')) | return env.templateTitle:subPageTitle(message('print-subpage')) | ||
end | end | ||
function envFuncs.protectionLevels() | function envFuncs.protectionLevels() | ||
-- The protection levels table of the title object. | -- The protection levels table of the title object. | ||
return env.title.protectionLevels | return env.title.protectionLevels | ||
end | end | ||
function envFuncs.subjectSpace() | function envFuncs.subjectSpace() | ||
-- The subject namespace number. | -- The subject namespace number. | ||
return mw.site.namespaces[env.title.namespace].subject.id | return mw.site.namespaces[env.title.namespace].subject.id | ||
end | end | ||
function envFuncs.docSpace() | function envFuncs.docSpace() | ||
-- The documentation namespace number. For most namespaces this is the same as the | -- The documentation namespace number. For most namespaces this is the same as the | ||
| Line 293: | Line 293: | ||
end | end | ||
end | end | ||
function envFuncs.docpageBase() | function envFuncs.docpageBase() | ||
-- The base page of the /doc, /sandbox, and /testcases subpages. | -- The base page of the /doc, /sandbox, and /testcases subpages. | ||
| Line 303: | Line 303: | ||
return docSpaceText .. ':' .. templateTitle.text | return docSpaceText .. ':' .. templateTitle.text | ||
end | end | ||
function envFuncs.compareUrl() | function envFuncs.compareUrl() | ||
-- Diff link between the sandbox and the main template using [[Special:ComparePages]]. | -- Diff link between the sandbox and the main template using [[Special:ComparePages]]. | ||
| Line 318: | Line 318: | ||
end | end | ||
end | end | ||
return env | return env | ||
end | end | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
-- Auxiliary templates | -- Auxiliary templates | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
function p.sandboxNotice(args, env) | function p.sandboxNotice(args, env) | ||
--[=[ | --[=[ | ||
| Line 391: | Line 391: | ||
return ret | return ret | ||
end | end | ||
function p.protectionTemplate(env) | function p.protectionTemplate(env) | ||
-- Generates the padlock icon in the top right. | -- Generates the padlock icon in the top right. | ||
| Line 420: | Line 420: | ||
end | end | ||
end | end | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
-- Start box | -- Start box | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
p.startBox = makeInvokeFunc('_startBox') | p.startBox = makeInvokeFunc('_startBox') | ||
function p._startBox(args, env) | function p._startBox(args, env) | ||
--[[ | --[[ | ||
| Line 456: | Line 456: | ||
end | end | ||
end | end | ||
function p.makeStartBoxLinksData(args, env) | function p.makeStartBoxLinksData(args, env) | ||
--[[ | --[[ | ||
| Line 479: | Line 479: | ||
return nil | return nil | ||
end | end | ||
local data = {} | local data = {} | ||
data.title = title | data.title = title | ||
| Line 503: | Line 503: | ||
return data | return data | ||
end | end | ||
function p.renderStartBoxLinks(data) | function p.renderStartBoxLinks(data) | ||
--[[ | --[[ | ||
| Line 509: | Line 509: | ||
-- @data - a table of data generated by p.makeStartBoxLinksData | -- @data - a table of data generated by p.makeStartBoxLinksData | ||
--]] | --]] | ||
local function escapeBrackets(s) | local function escapeBrackets(s) | ||
-- Escapes square brackets with HTML entities. | -- Escapes square brackets with HTML entities. | ||
| Line 516: | Line 516: | ||
return s | return s | ||
end | end | ||
local ret | local ret | ||
local docTitle = data.docTitle | local docTitle = data.docTitle | ||
| Line 536: | Line 536: | ||
return ret | return ret | ||
end | end | ||
function p.makeStartBoxData(args, env, links) | function p.makeStartBoxData(args, env, links) | ||
--[=[ | --[=[ | ||
| Line 561: | Line 561: | ||
end | end | ||
local data = {} | local data = {} | ||
-- Heading | -- Heading | ||
local heading = args.heading -- Blank values are not removed. | local heading = args.heading -- Blank values are not removed. | ||
| Line 579: | Line 579: | ||
data.heading = message('other-namespaces-heading') | data.heading = message('other-namespaces-heading') | ||
end | end | ||
-- Heading CSS | -- Heading CSS | ||
local headingStyle = args['heading-style'] | local headingStyle = args['heading-style'] | ||
| Line 591: | Line 591: | ||
data.headingFontSize = '150%' | data.headingFontSize = '150%' | ||
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 | ||
| Line 598: | Line 598: | ||
data.links = links | data.links = links | ||
end | end | ||
return data | return data | ||
end | end | ||
function p.renderStartBox(data) | function p.renderStartBox(data) | ||
-- Renders the start box html. | -- Renders the start box html. | ||
| Line 625: | Line 625: | ||
return tostring(sbox) | return tostring(sbox) | ||
end | end | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
-- Documentation content | -- Documentation content | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
p.content = makeInvokeFunc('_content') | p.content = makeInvokeFunc('_content') | ||
function p._content(args, env) | function p._content(args, env) | ||
-- Displays the documentation contents | -- Displays the documentation contents | ||
| Line 647: | Line 647: | ||
return '\n' .. (content or '') .. '\n' | return '\n' .. (content or '') .. '\n' | ||
end | end | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
-- End box | -- End box | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
p.endBox = makeInvokeFunc('_endBox') | p.endBox = makeInvokeFunc('_endBox') | ||
function p._endBox(args, env) | function p._endBox(args, env) | ||
--[=[ | --[=[ | ||
| Line 667: | Line 667: | ||
-- The HTML is generated by the {{fmbox}} template, courtesy of [[Module:Message box]]. | -- The HTML is generated by the {{fmbox}} template, courtesy of [[Module:Message box]]. | ||
--]=] | --]=] | ||
-- Get environment data. | -- Get environment data. | ||
env = env or p.getEnvironment(args) | env = env or p.getEnvironment(args) | ||
| Line 675: | Line 675: | ||
return nil | return nil | ||
end | end | ||
-- Check whether we should output the end box at all. Add the end | -- Check whether we should output the end box at all. Add the end | ||
-- box by default if the documentation exists or if we are in the | -- box by default if the documentation exists or if we are in the | ||
| Line 690: | Line 690: | ||
return nil | return nil | ||
end | end | ||
-- Assemble the arguments for {{fmbox}}. | -- Assemble the arguments for {{fmbox}}. | ||
local fmargs = {} | local fmargs = {} | ||
| Line 697: | Line 697: | ||
fmargs.style = message('fmbox-style') -- Sets 'background-color: #ecfcf4' | fmargs.style = message('fmbox-style') -- Sets 'background-color: #ecfcf4' | ||
fmargs.textstyle = message('fmbox-textstyle') -- 'font-style: italic;' | fmargs.textstyle = message('fmbox-textstyle') -- 'font-style: italic;' | ||
-- Assemble the fmbox text field. | -- Assemble the fmbox text field. | ||
local text = '' | local text = '' | ||
| Line 724: | Line 724: | ||
end | end | ||
fmargs.text = text | fmargs.text = text | ||
return messageBox.main('fmbox', fmargs) | return messageBox.main('fmbox', fmargs) | ||
end | end | ||
function p.makeDocPageBlurb(args, env) | function p.makeDocPageBlurb(args, env) | ||
--[=[ | --[=[ | ||
| Line 773: | Line 773: | ||
return ret | return ret | ||
end | end | ||
function p.makeExperimentBlurb(args, env) | function p.makeExperimentBlurb(args, env) | ||
--[[ | --[[ | ||
| Line 870: | Line 870: | ||
return message(messageName, {sandboxLinks, testcasesLinks}) | return message(messageName, {sandboxLinks, testcasesLinks}) | ||
end | end | ||
function p.makeCategoriesBlurb(args, env) | function p.makeCategoriesBlurb(args, env) | ||
--[[ | --[[ | ||
| Line 887: | Line 887: | ||
return message('add-categories-blurb', {docPathLink}) | return message('add-categories-blurb', {docPathLink}) | ||
end | end | ||
function p.makeSubpagesBlurb(args, env) | function p.makeSubpagesBlurb(args, env) | ||
--[[ | --[[ | ||
| Line 893: | Line 893: | ||
-- @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 | ||
-- Messages: | -- Messages: | ||
-- 'template-pagetype' --> 'template' | -- 'template-pagetype' --> 'template' | ||
| Line 919: | Line 919: | ||
return message('subpages-blurb', {subpagesLink}) | return message('subpages-blurb', {subpagesLink}) | ||
end | end | ||
function p.makePrintBlurb(args, env) | function p.makePrintBlurb(args, env) | ||
--[=[ | --[=[ | ||
| Line 949: | Line 949: | ||
return ret | return ret | ||
end | end | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
-- Tracking categories | -- Tracking categories | ||
---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ||
function p.addTrackingCategories(env) | function p.addTrackingCategories(env) | ||
--[[ | --[[ | ||
-- Check if {{documentation}} is transcluded on a /doc or /testcases page. | -- Check if {{documentation}} is transcluded on a /doc or /testcases page. | ||
-- @env - environment table containing title objects, etc., generated with p.getEnvironment | -- @env - environment table containing title objects, etc., generated with p.getEnvironment | ||
-- Messages: | -- Messages: | ||
-- 'display-strange-usage-category' --> true | -- 'display-strange-usage-category' --> true | ||
| Line 985: | Line 985: | ||
return ret | return ret | ||
end | end | ||
return p | return p | ||