Module:Documentation
Documentation for this module may be created at Module:Documentation/doc
-- This module implements {{documentation}}.
----------------------------------------------------------------------------
-- Configuration
----------------------------------------------------------------------------
-- Here you can set the values of the parameters and messages used in this module, so that it
-- can be easily ported to other wikis.
local cfg = {}
-- Argument names
-- The following are all names of arguments that affect the behaviour of {{documentation}}.
-- The comments next to the configuration values are the effects that the argument has
-- on the module. (Not the effects of the argument names themselves.)
cfg.livepageArg = 'livepage' -- Name of the live template; used in {{template sandbox notice}}.
cfg.headingArg = 'heading' -- Custom heading used in the start box.
cfg.preloadArg = 'preload' -- Custom preload page for creating documentation.
cfg.headingStyleArg = 'heading-style' -- Custom CSS style for the start box heading.
cfg.contentArg = 'content' -- Passes documentation content directly from the {{documentation}} invocation.
cfg.linkBoxArg = 'link box' -- Specifies a custom link box (end box) or prevents it from being generated.
-- Argument values
-- The following are argument values that are checked by the module.
cfg.linkBoxOff = 'off' -- The value to send to cfg.linkBoxArg to turn the link box off.
-- Software settings
-- The following are software settings that may change from wiki to wiki. For example, the classes
-- defined in commons.css or the names of templates.
cfg.docSubpage = 'doc' -- The name of the subpage typically used for documentation pages.
cfg.sandboxSubpage = 'sandbox' -- The name of the template subpage typically used for sandboxes.
cfg.testcasesSubpage = 'testcases' -- The name of the template subpage typically used for test cases.
cfg.mainDivId = 'template-documentation' -- The "id" attribute of the main HTML "div" tag.
cfg.mainDivClasses = 'template-documentation iezoomfix' -- The CSS classes added to the main HTML "div" tag.
cfg.sandboxNoticeTemplate = 'template sandbox notice' -- The name of the template to display at the top of sandbox pages.
cfg.sandboxNoticeLivepageParam = 1 -- The parameter of the sandbox notice template to send the cfg.livepageArg to.
cfg.protectionTemplate = 'pp-template' -- The name of the template that displays the protection icon (a padlock on enwiki).
cfg.protectionTemplateArgs = {docusage = 'yes'} -- Any arguments to send to the protection template.
cfg.startBoxLinkclasses = 'mw-editsection plainlinks' -- The CSS classes used for the [view][edit][history] or [create] links in the start box.
cfg.startBoxLinkId = 'doc_editlinks' -- The HTML "id" attribute for the links in the start box.
cfg.fileDocpagePreload = 'Template:Documentation/preload-filespace' -- A preload file for documentation page in the file namespace.
cfg.docpagePreload = 'Template:Documentation/preload-filespace' -- A preload file for template documentation pages in all namespaces.
-- Settings for the {{fmbox}} template.
cfg.fmboxIdParam = 'id' -- The name of the "id" parameter of {{fmbox}}.
cfg.fmboxId = 'documentation-meta-data' -- The id sent to the "id" parameter of the {{fmbox}} template.
cfg.fmboxImageParam = 'image' -- The name of the "image" parameter of {{fmbox}}.
cfg.fmboxImageNone = 'none' -- The value to suppress image output from the "image" parameter of {{fmbox}}.
cfg.fmboxStyleParam = 'style' -- The name of the "style" parameter of {{fmbox}}.
cfg.fmboxStyle = 'background-color: #ecfcf4' -- The value sent to the style parameter of {{fmbox}}.
cfg.fmboxTextstyleParam = 'textstyle' -- The name of the "textstyle" parameter of {{fmbox}}.
cfg.fmboxTextstyle = 'font-style: italic;' -- The value send to the "textstyle parameter of {{fmbox}}.
-- Display settings
-- The following settings configure the values displayed by the module.
cfg.viewLinkDisplay = 'view' -- The text to display for "view" links.
cfg.editLinkDisplay = 'edit' -- The text to display for "edit" links.
cfg.historyLinkDisplay = 'history' -- The text to display for "history" links.
cfg.purgeLinkDisplay = 'purge' -- The text to display for "purge" links.
cfg.createLinkDisplay = 'create' -- The text to display for "create" links.
cfg.sandboxLinkDisplay = 'sandbox' -- The text to display for "sandbox" links.
cfg.sandboxEditLinkDisplay = 'edit' -- The text to display for sandbox "edit" links.
cfg.sandboxCreateLinkDisplay = 'create' -- The text to display for sandbox "create" links.
cfg.compareLinkDisplay = 'diff' -- The text to display for "compare" links.
cfg.mirrorLinkDisplay = 'mirror' -- The text to display for "mirror" links.
cfg.testcasesLinkDisplay = 'testcases' -- The text to display for "testcases" links.
cfg.testcasesEditLinkDisplay = 'edit' -- The text to display for test cases "edit" links.
cfg.testcasesCreateLinkDisplay = 'create' -- The text to display for test cases "create" links.
cfg.documentationIconWikitext = '[[File:Template-info.png|50px|link=|alt=Documentation icon]]' -- The wikitext for the icon shown at the top of the template.
cfg.templateNamespaceHeading = 'Template documentation' -- The heading shown in the template namespace.
cfg.moduleNamespaceHeading = 'Module documentation' -- The heading shown in the module namespace.
cfg.fileNamespaceHeading = 'Summary' -- The heading shown in the file namespace.
cfg.otherNamespacesHeading = 'Documentation' -- The heading shown in other namespaces.
----------------------------------------------------------------------------
-- End configuration
----------------------------------------------------------------------------
-- Get required modules.
local getArgs = require('Module:Arguments').getArgs
local htmlBuilder = require('Module:HtmlBuilder')
local messageBox = require('Module:Message box')
local p = {}
-- Constants.
local currentTitle = mw.title.getCurrentTitle()
local subjectSpace = mw.site.namespaces[currentTitle.namespace].subject.id
----------------------------------------------------------------------------
-- Helper functions
----------------------------------------------------------------------------
local function makeWikilink(page, display)
if display then
return mw.ustring.format('[[%s|%s]]', page, display)
else
return mw.ustring.format('[[%s]]', page)
end
end
local function makeUrlLink(url, display)
return mw.ustring.format('[%s %s]', url, display)
end
local function makeToolbar(...)
local ret = {}
local lim = select('#', ...)
if lim < 1 then
return nil
end
for i = 1, lim do
ret[#ret + 1] = select(i, ...)
end
return '<small style="font-style: normal;">(' .. table.concat(ret, ' | ') .. ')</small>'
end
----------------------------------------------------------------------------
-- Argument processing
----------------------------------------------------------------------------
local function makeInvokeFunc(funcName)
return function (frame)
local headingArg = cfg.headingArg
local args = getArgs(frame, {
valueFunc = function (key, value)
if type(value) == 'string' then
value = value:match('^%s*(.-)%s*$') -- Remove whitespace.
if key == headingArg or value ~= '' then
return value
else
return nil
end
else
return value
end
end
})
return p[funcName](args)
end
end
----------------------------------------------------------------------------
-- Main functions
----------------------------------------------------------------------------
p.main = makeInvokeFunc('_main')
function p._main(args)
local root = htmlBuilder.create()
root
.wikitext(p.protectionTemplate())
.wikitext(p.sandboxNotice(args))
-- This div tag is from {{documentation/start box}}, but moving it here
-- so that we don't have to worry about unclosed tags.
.tag('div')
.attr('id', cfg.mainDivId)
.addClass(cfg.mainDivClasses)
.wikitext(p._startBox(args))
.wikitext(p._content(args))
.tag('div')
.css('clear', 'both') -- So right or left floating items don't stick out of the doc box.
.done()
.done()
.wikitext(p._endBox(args))
.wikitext(p.addTrackingCategories())
return tostring(root)
end
function p.sandboxNotice(args)
local sandboxNoticeTemplate = cfg.sandboxNoticeTemplate
if not (sandboxNoticeTemplate and currentTitle.subpageText == cfg.sandboxSubpage) then
return nil
end
local frame = mw.getCurrentFrame()
local notice = htmlBuilder.create()
notice
.tag('div')
.css('clear', 'both')
.done()
.wikitext(frame:expandTemplate{title = sandboxNoticeTemplate, args = {[cfg.sandboxNoticeLivepageParam] = args[cfg.livepageArg]}})
return tostring(notice)
end
function p.protectionTemplate()
local protectionTemplate = cfg.protectionTemplate
if not (protectionTemplate and currentTitle.namespace == 10) then
-- Don't display the protection template if we are not in the template namespace.
return nil
end
local frame = mw.getCurrentFrame()
local function getProtectionLevel(protectionType)
-- Gets the protection level for the current page.
local level = frame:callParserFunction('PROTECTIONLEVEL', protectionType)
if level ~= '' then
return level
else
return nil -- The parser function returns the blank string if there is no match.
end
end
if getProtectionLevel('move') == 'sysop' or getProtectionLevel('edit') then
-- The page is full-move protected, or full, template, or semi-protected.
return frame:expandTemplate{title = protectionTemplate, args = cfg.protectionTemplateArgs}
end
return nil
end
p.startBox = makeInvokeFunc('_startBox')
function p._startBox(args)
-- Arg processing from {{documentation}}.
local preload = args[cfg.preloadArg] -- Allow custom preloads.
local heading = args[cfg.headingArg] -- Blank values are not removed.
local headingStyle = args[cfg.headingStyleArg]
local content = args[cfg.contentArg]
local docspace = p.docspace()
local docname = args[1] -- Other docname, if fed.
local templatePage = p.templatePage()
-- Arg processing from {{documentation/start box2}}.
local docpage
if docname then
docpage = docname
else
local namespace = docspace or currentTitle.nsText
local pagename = templatePage or currentTitle.text
docpage = namespace .. ':' .. pagename .. '/' .. cfg.docSubpage
end
local docTitle = mw.title.new(docpage)
local docExist = docTitle.exists
-- Output from {{documentation/start box}}.
-- First, check the heading parameter.
if heading == '' then
-- Heading is defined but blank, so do nothing.
return nil
end
-- Build the start box div.
local sbox = htmlBuilder.create('div')
sbox
.css('padding-bottom', '3px')
.css('border-bottom', '1px solid #aaa')
.css('margin-bottom', '1ex')
-- Make the heading.
local hspan = sbox.tag('span')
if headingStyle then
hspan.cssText(headingStyle)
elseif subjectSpace == 10 then
-- We are in the template or template talk namespaces.
hspan
.css('font-weight', 'bold')
.css('fond-size', '125%')
else
hspan.css('font-size', '150%')
end
if heading then
-- "heading" has data.
hspan.wikitext(heading)
elseif subjectSpace == 10 then -- Template namespace
hspan.wikitext(cfg.documentationIconWikitext .. ' ' .. cfg.templateNamespaceHeading)
elseif subjectSpace == 828 then -- Module namespace
hspan.wikitext(cfg.documentationIconWikitext .. ' ' .. cfg.moduleNamespaceHeading)
elseif subjectSpace == 6 then -- File namespace
hspan.wikitext(cfg.fileNamespaceHeading)
else
hspan.wikitext(cfg.otherNamespaceHeading)
end
-- Add the [view][edit][history][purge] or [create] links.
-- Check for the content parameter first, as we don't need the links if the documentation
-- content is being entered directly onto the template page.
if not content then
local lspan = sbox.tag('span') -- lspan is short for "link span".
lspan
.addClass(cfg.startBoxLinkclasses)
.attr('id', cfg.startBoxLinkId)
if docExist then
local viewLink = makeWikilink(docpage, cfg.viewLinkDisplay)
local editLink = makeUrlLink(docTitle:fullUrl{action = 'edit'}, cfg.editLinkDisplay)
local historyLink = makeUrlLink(docTitle:fullUrl{action = 'history'}, cfg.historyLinkDisplay)
local purgeLink = makeUrlLink(docTitle:fullUrl{action = 'purge'}, cfg.purgeLinkDisplay)
local text = '[%s] [%s] [%s] [%s]'
text = text:gsub('%[', '[') -- Replace square brackets with HTML entities.
text = text:gsub('%]', ']')
lspan.wikitext(mw.ustring.format(text, viewLink, editLink, historyLink, purgeLink))
else
if not preload then
if subjectSpace == 6 then -- File namespace
preload = cfg.fileDocpagePreload
else
preload = cfg.docpagePreload
end
end
lspan.wikitext(makeUrlLink(docTitle:fullUrl{action = 'edit', preload = preload}, cfg.createLinkDisplay))
end
end
return tostring(sbox)
end
p.content = makeInvokeFunc('_content')
function p._content(args)
local content = args[cfg.contentArg]
if not content then
local docpage = args[1]
if docpage and mw.title.new(docpage).exists then
local frame = mw.getCurrentFrame()
content = frame:preprocess('{{ ' .. docpage .. ' }}')
else
docpage = p.docspace() .. ':' .. p.templatePage() .. '/' .. cfg.docSubpage
if mw.title.new(docpage).exists then
local frame = mw.getCurrentFrame()
content = frame:preprocess('{{ ' .. docpage .. ' }}')
end
end
end
-- The line breaks below are necessary so that "=== Headings ===" at the start and end
-- of docs are interpreted correctly.
return '\n' .. (content or '') .. '\n'
end
p.endBox = makeInvokeFunc('_endBox')
function p._endBox(args)
-- Argument processing in {{documentation}}.
local content = args[cfg.contentArg]
local linkBox = args[cfg.linkBoxArg] -- So "link box=off" works.
local docspace = p.docspace()
local docname = args[1] -- Other docname, if fed.
local templatePage = p.templatePage()
-- Argument processing in {{documentation/end box2}}.
local docpageRoot = (docspace or currentTitle.nsText) .. ':' .. (templatePage or currentTitle.text)
local docpage
if docname then
docpage = docname
else
docpage = docpageRoot .. '/' .. cfg.docSubpage
end
local docTitle = mw.title.new(docpage)
local docExist = docTitle.exists
local docnameFed = args[1] and true
local sandbox = docpageRoot .. '/' .. cfg.sandboxSubpage
local testcases = docpageRoot .. '/' .. cfg.testcasesSubpage
templatePage = currentTitle.nsText .. ':' .. templatePage
-- Output from {{documentation/end box}}
-- First, 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 user, module or template namespaces.
if linkBox == cfg.linkBoxOff or not (docExist or subjectSpace == 2 or subjectSpace == 828 or subjectSpace == 10) then
return nil
end
-- Assemble the arguments for {{fmbox}}.
local fmargs = {}
fmargs[cfg.fmboxIdParam] = cfg.fmboxId -- Sets fmargs.id = 'documentation-meta-data'
fmargs[cfg.fmboxImageParam] = cfg.fmboxImageNone -- Sets fmargs.image = 'none'
fmargs[cfg.fmboxStyleParam] = cfg.fmboxStyle -- Sets fmargs.style = 'background-color: #ecfcf4'
fmargs[cfg.fmboxTextstyleParam] = cfg.fmboxTextstyle -- Sets fmargs.textstyle = 'font-style: italic;'
-- Assemble the fmbox text field.
local text = ''
if linkBox then
-- Use custom link box content if it is defined.
text = text .. linkBox
else
if docExist then
-- /doc exists; link to it.
local docLink = makeWikilink(docpage)
local editLink = makeUrlLink(docTitle:fullUrl{action = 'edit'}, cfg.editLinkDisplay)
local historyLink = makeUrlLink(docTitle:fullUrl{action = 'history'}, cfg.historyLinkDisplay)
text = text .. 'The above [[Wikipedia:Template documentation|documentation]] is [[Wikipedia:Transclusion|transcluded]] from '
.. docLink .. '. ' .. makeToolbar(editLink, historyLink) .. '<br />'
elseif subjectSpace == 828 then
-- /doc does not exist; ask to create it.
local createLink = makeUrlLink(docTitle:fullUrl{action = 'edit', preload = 'Template:Documentation/preload-module-doc'}, cfg.createLinkDisplay)
text = text .. 'You might want to ' .. createLink .. ' a documentation page for this [[Wikipedia:Lua|Scribunto module]].<br />'
end
-- Add links to /sandbox and /testcases when appropriate.
if subjectSpace == 2 or subjectSpace == 828 or subjectSpace == 10 then
-- We are in the user, module or template namespaces.
local pagePossessive = subjectSpace == 828 and "module's" or "template's"
text = text .. 'Editors can experiment in this ' .. pagePossessive .. ' '
local sandboxTitle = mw.title.new(sandbox)
if sandboxTitle.exists then
local sandboxLink = makeWikilink(sandbox, cfg.sandboxLinkDisplay)
local sandboxEditLink = makeUrlLink(sandboxTitle:fullUrl{action = 'edit'}, cfg.sandboxEditLinkDisplay)
local compareLink = makeUrlLink(mw.title.new('Special:ComparePages'):fullUrl{page1 = templatePage, page2 = sandbox}, cfg.compareLinkDisplay)
text = text .. sandboxLink .. ' ' .. makeToolbar(sandboxEditLink, compareLink)
else
local sandboxPreload = 'Template:Documentation/preload-' .. (subjectSpace == 828 and 'module-' or '') .. 'sandbox'
local sandboxCreateLink = makeUrlLink(sandboxTitle:fullUrl{action = 'edit', preload = sandboxPreload}, cfg.sandboxCreateLinkDisplay)
local mirrorSummary = 'Create sandbox version of ' .. makeWikilink(templatePage)
local mirrorLink = makeUrlLink(sandboxTitle:fullUrl{action = 'edit', preload = templatePage, summary = mirrorSummary}, cfg.mirrorLinkDisplay)
text = text .. cfg.sandboxLinkDisplay .. ' ' .. makeToolbar(sandboxCreateLink, mirrorLink)
end
text = text .. ' and '
local testcaseTitle = mw.title.new(testcases)
if testcaseTitle.exists then
local testcasesLink = makeWikilink(testcases, cfg.testcasesLinkDisplay)
local testcasesEditLink = makeUrlLink(testcaseTitle:fullUrl{action = 'edit'}, cfg.testcasesEditLinkDisplay)
text = text .. testcasesLink .. ' ' .. makeToolbar(testcasesEditLink)
else
local testcasesPreload = 'Template:Documentation/preload-' .. (subjectSpace == 828 and 'module-' or '') .. 'testcases'
local testcasesCreateLink = makeUrlLink(testcaseTitle:fullUrl{action = 'edit', preload = testcasesPreload}, cfg.testcasesCreateLinkDisplay)
text = text .. cfg.testcasesLinkDisplay .. ' ' .. makeToolbar(testcasesCreateLink)
end
text = text .. ' pages. <br />'
-- Show the categories text, but not if "content" fed or "docname fed" since then it is unclear where to add the categories.
if not content and not docnameFed then
text = text .. 'Please add categories to the ' .. makeWikilink(docpage, '/' .. cfg.docSubpage) .. ' subpage.'
end
-- Show the "subpages" link.
if subjectSpace ~= 6 then -- Don't show the link in file space.
local pagetype
if subjectSpace == 10 then
pagetype = 'template'
elseif subjectSpace == 828 then
pagetype = 'module'
else
pagetype = 'page'
end
text = text .. ' ' .. makeWikilink('Special:PrefixIndex/' .. templatePage .. '/', 'Subpages of this ' .. pagetype)
end
-- Show the "print" link if it exists.
local printPage = templatePage .. '/Print'
local printTitle = mw.title.new(printPage)
if printTitle.exists then
text = text .. '<br />A [[Help:Books/for experts#Improving the book layout|print version]] of this template exists at '
.. makeWikilink(printPage, '/Print') .. '. If you make a change to this template, please update the print version as well.'
.. '[[Category:Templates with print versions]]'
end
end
end
fmargs.text = text
-- Return the fmbox output.
return messageBox.main('fmbox', fmargs)
end
function p.addTrackingCategories()
-- Check if {{documentation}} is transcluded on a /doc or /testcases page.
local ret = ''
local subpage = currentTitle.subpageText
if subpage == cfg.docSubpage or subpage == cfg.testcasesSubpage then
local sort = (currentTitle.namespace == 0 and 'Main:' or '') .. currentTitle.prefixedText -- Sort on namespace.
ret = ret .. makeWikilink('Category:Wikipedia pages with strange ((documentation)) usage', sort)
end
return ret
end
function p.docspace()
-- Determines the namespace of the documentation.
if subjectSpace == 0 or subjectSpace == 6 or subjectSpace == 8 or subjectSpace == 14 then
-- Pages in the Article, File, MediaWiki or Category namespaces must have their
-- /doc, /sandbox and /testcases pages in talk space.
return mw.site.namespaces[subjectSpace].talk.name
else
return currentTitle.subjectNsText
end
end
function p.templatePage()
-- Determines the template page. No namespace or interwiki prefixes are included.
local subpage = currentTitle.subpageText
if subpage == cfg.sandboxSubpage or subpage == cfg.testcasesSubpage then
return currentTitle.baseText
else
return currentTitle.text
end
end
return p