CivWiki

Module:Documentation: Difference between revisions

← Older edit
Content deleted Content added
don't check that we are not in the file namespace before adding the subpage blurb, as we already know we're either in the user, template or module namespace
m 1 revision imported from wikipedia:Module:Documentation
 
(56 intermediate revisions by 20 users not shown)
Line 3:
-- Get required modules.
local getArgs = require('Module:Arguments').getArgs
local htmlBuilder = require('Module:HtmlBuilder')
local messageBox = require('Module:Message box')
 
-- Get the config table.
Line 28 ⟶ 26:
-- If the table valArray is present, strings such as $1, $2 etc. in the
-- message are substituted with values from the table keys [1], [2] etc.
-- For example, if the message cfg.fooMessage"foo-message" had the value 'Foo $2 bar $1.',
-- message('foo-message', {'baz', 'qux'}) would return "Foo qux bar baz."
--]]
Line 45 ⟶ 43:
end
 
local ret =return ugsub(msg, '$([1-9][0-9]*)', getMessageVal)
return ret
end
 
Line 83 ⟶ 80:
ret[#ret + 1] = select(i, ...)
end
-- 'documentation-toolbar'
return '<small style="font-style: normal;">(' .. table.concat(ret, ' &#124; ') .. ')</small>'
return '<span class="' .. message('toolbar-class') .. '">('
.. table.concat(ret, ' &#124; ') .. ')</span>'
end
 
Line 113 ⟶ 112:
 
----------------------------------------------------------------------------
-- MainEntry functionpoints
----------------------------------------------------------------------------
 
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
 
p.main = makeInvokeFunc('_main')
Line 122 ⟶ 129:
-- This function defines logic flow for the module.
-- @args - table of arguments passed by the user
--
-- Messages:
-- 'main-div-id' --> 'template-documentation'
-- 'main-div-classes' --> 'template-documentation iezoomfix'
--]]
local env = p.getEnvironment(args)
local root = htmlBuildermw.html.create()
root
.:wikitext(p.protectionTemplate_getModuleWikitext(args, env))
.:wikitext(p.sandboxNoticeprotectionTemplate(args, env))
:wikitext(p.sandboxNotice(args, env))
-- This div tag is from {{documentation/start box}}, but moving it here
:tag('div')
-- so that we don't have to worry about unclosed tags.
-- 'documentation-container'
.tag('div')
.attr:addClass('id', message('main-div-idcontainer'))
:newline()
.addClass(message('main-div-classes'))
.newline:tag('div')
-- 'documentation'
.wikitext(p._startBox(args, env))
:addClass(message('main-div-classes'))
.wikitext(p._content(args, env))
.tag :newline('div')
:wikitext(p._startBox(args, env))
.css('clear', 'both') -- So right or left floating items don't stick out of the doc box.
:wikitext(p._content(args, env))
.newline()
.done:tag('div')
-- 'documentation-clear'
.done()
:addClass(message('clear'))
.wikitext(p._endBox(args, env))
.newline :done()
:newline()
.wikitext(p.addTrackingCategories(env))
:done()
return tostring(root)
:wikitext(p._endBox(args, env))
:done()
:wikitext(p.addTrackingCategories(env))
-- 'Module:Documentation/styles.css'
return mw.getCurrentFrame():extensionTag (
'templatestyles', '', {src=cfg['templatestyles']
}) .. tostring(root)
end
 
Line 157 ⟶ 167:
function p.getEnvironment(args)
--[[
-- Returns a table with information about the environment, including title objects and other namespace- or
-- objects and other namespace- or path-related data.
-- @args - table of arguments passed by the user
--
Line 170 ⟶ 180:
--
-- Data includes:
-- env.protectionLevels - the protection levels table of the title object.
-- env.subjectSpace - the number of the title's subject namespace.
-- env.docSpace - the number of the namespace the title puts its documentation in.
Line 269 ⟶ 280:
--]]
return env.templateTitle:subPageTitle(message('print-subpage'))
end
 
function envFuncs.protectionLevels()
-- The protection levels table of the title object.
return env.title.protectionLevels
end
 
Line 277 ⟶ 293:
 
function envFuncs.docSpace()
-- The documentation namespace number. For most namespaces this is the same as the
-- same as the subject namespace. However, pages in the Article, File, MediaWiki or Category
-- MediaWiki or Category namespaces must have their /doc, /sandbox and /testcases pages in talk space.
-- /testcases pages in talk space.
local subjectSpace = env.subjectSpace
if subjectSpace == 0 or subjectSpace == 6 or subjectSpace == 8 or subjectSpace == 14 then
Line 302 ⟶ 319:
local templateTitle = env.templateTitle
local sandboxTitle = env.sandboxTitle
if templateTitle.exists and sandboxTitle.exists then
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)
else
return nil
end
end
 
Line 315 ⟶ 336:
-- Auxiliary templates
----------------------------------------------------------------------------
 
p.getModuleWikitext = makeInvokeFunc('_getModuleWikitext')
 
function p._getModuleWikitext(args, env)
local currentTitle = mw.title.getCurrentTitle()
if currentTitle.contentModel ~= 'Scribunto' then return end
pcall(require, currentTitle.prefixedText) -- if it fails, we don't care
local moduleWikitext = package.loaded["Module:Module wikitext"]
if moduleWikitext then
return moduleWikitext.main()
end
end
 
function p.sandboxNotice(args, env)
Line 323 ⟶ 356:
--
-- Messages:
-- 'sandbox-notice-image' --> '[[Image:Sandbox.pngsvg|50px|alt=|link=]]'
-- 'sandbox-notice-blurb' --> 'This is the [[Wikipedia:Template test cases|template sandbox]] page$1 for $12.'
-- 'sandbox-notice-diff-blurb' --> 'This is the [[Wikipedia:Template test cases|template sandbox]] page$1 for $12 ($23).'
-- 'sandbox-notice-pagetype-template' --> '[[Wikipedia:Template test cases|template sandbox]] page'
-- 'sandbox-notice-pagetype-module' --> '[[Wikipedia:Template test cases|module sandbox]] page'
-- 'sandbox-notice-pagetype-other' --> 'sandbox page'
-- 'sandbox-notice-compare-link-display' --> 'diff'
-- 'sandbox-notice-testcases-blurb' --> 'See also the companion subpage for $1.'
Line 334 ⟶ 370:
local sandboxTitle = env.sandboxTitle
local templateTitle = env.templateTitle
local subjectSpace = env.subjectSpace
if not (title and sandboxTitle and templateTitle and mw.title.equals(title, sandboxTitle)) then
if not (subjectSpace and title and sandboxTitle and templateTitle
and mw.title.equals(title, sandboxTitle)) then
return nil
end
Line 343 ⟶ 381:
-- "This is the template sandbox for [[Template:Foo]] (diff)."
local text = ''
local pagetype
local frame = mw.getCurrentFrame()
if subjectSpace == 10 then
local isPreviewing = frame:preprocess('{{REVISIONID}}') == '' -- True if the page is being previewed.
pagetype = message('sandbox-notice-pagetype-template')
elseif subjectSpace == 828 then
pagetype = message('sandbox-notice-pagetype-module')
else
pagetype = message('sandbox-notice-pagetype-other')
end
local templateLink = makeWikilink(templateTitle.prefixedText)
local compareUrl = env.compareUrl
if isPreviewing or not compareUrl then
text = text .. message('sandbox-notice-blurb', {templateLink})
else
local compareDisplay = message('sandbox-notice-compare-link-display')
local compareLink = makeUrlLink(compareUrl, compareDisplay)
text = text .. message('sandbox-notice-diff-blurb', {pagetype, templateLink, compareLink})
else
text = text .. message('sandbox-notice-blurb', {pagetype, templateLink})
end
-- Get the test cases page blurb if the page exists. This is something like
Line 358 ⟶ 402:
local testcasesTitle = env.testcasesTitle
if testcasesTitle and testcasesTitle.exists then
if testcasesTitle.contentModel == "Scribunto" then
local testcasesLinkDisplay = message('sandbox-notice-testcases-link-display')
local testcasesLinkDisplay = message('sandbox-notice-testcases-link-display')
local testcasesLink = makeWikilink(testcasesTitle.prefixedText, testcasesLinkDisplay)
text local testcasesRunLinkDisplay = text .. '<br />' .. message('sandbox-notice-testcases-blurbrun-link-display', {testcasesLink})
local testcasesLink = makeWikilink(testcasesTitle.prefixedText, testcasesLinkDisplay)
local testcasesRunLink = makeWikilink(testcasesTitle.talkPageTitle.prefixedText, testcasesRunLinkDisplay)
text = text .. '<br />' .. message('sandbox-notice-testcases-run-blurb', {testcasesLink, testcasesRunLink})
else
local testcasesLinkDisplay = message('sandbox-notice-testcases-link-display')
local testcasesLink = makeWikilink(testcasesTitle.prefixedText, testcasesLinkDisplay)
text = text .. '<br />' .. message('sandbox-notice-testcases-blurb', {testcasesLink})
end
end
-- Add the sandbox to the sandbox category.
omargs.text = text .. makeCategoryLink(message('sandbox-category'))
 
omargs.text = text
-- 'documentation-clear'
return messageBox.main('ombox', omargs)
return '<div class="' .. message('clear') .. '"></div>'
.. require('Module:Message box').main('ombox', omargs)
end
 
Line 374 ⟶ 428:
-- 'protection-template' --> 'pp-template'
-- 'protection-template-args' --> {docusage = 'yes'}
local titleprotectionLevels = env.titleprotectionLevels
if not protectionLevels then
local protectionTemplate = message('protection-template')
local namespace = title.namespace
if not (protectionTemplate and (namespace == 10 or namespace == 828)) then
-- Don't display the protection template if we are not in the template or module namespaces.
return nil
end
local editProt = protectionLevels.edit and protectionLevels.edit[1]
local frame = mw.getCurrentFrame()
local moveProt = protectionLevels.move and protectionLevels.move[1]
local function getProtectionLevel(protectionType, page)
if editProt then
-- Gets the protection level for page, or for the current page if page is not specified.
-- The page is edit-protected.
local level = frame:callParserFunction('PROTECTIONLEVEL', protectionType, page)
return require('Module:Protection banner')._main{
if level ~= '' then
message('protection-reason-edit'), small = true
return level
else}
elseif moveProt and moveProt ~= 'autoconfirmed' then
return nil -- The parser function returns the blank string if there is no match.
-- The page is move-protected but not edit-protected. Exclude move
end
-- protection with the level "autoconfirmed", as this is equivalent to
end
-- no move protection at all.
local prefixedTitle = title.prefixedText
return require('Module:Protection banner')._main{
if getProtectionLevel('move', prefixedTitle) == 'sysop' or getProtectionLevel('edit', prefixedTitle) then
action = 'move', small = true
-- The page is full-move protected, or full, template, or semi-protected.
}
return frame:expandTemplate{title = protectionTemplate, args = message('protection-template-args', nil, 'table')}
else
return nil
end
return nil
end
 
Line 415 ⟶ 467:
-- which generate the box HTML.
--]]
env = env or p.getEnvironment(args)
local links
local content = args.content
if not content or args[1] then
-- No need to include the links if the documentation is on the template page itself.
local linksData = p.makeStartBoxLinksData(args, env)
Line 446 ⟶ 499:
-- 'purge-link-display' --> 'purge'
-- 'file-docpage-preload' --> 'Template:Documentation/preload-filespace'
-- 'module-preload' --> 'Template:Documentation/preload-module-doc'
-- 'docpage-preload' --> 'Template:Documentation/preload'
-- 'create-link-display' --> 'create'
--]]
local datasubjectSpace = {}env.subjectSpace
-- Get title objects.
local title = env.title
local docTitle = env.docTitle
Line 456 ⟶ 509:
return nil
end
if docTitle.isRedirect then
docTitle = docTitle.redirectTarget
end
 
local data = {}
data.title = title
data.docTitle = docTitle
Line 466 ⟶ 524:
local preload = args.preload
if not preload then
if env.subjectSpace == 6 then -- File namespace
preload = message('file-docpage-preload')
elseif subjectSpace == 828 then -- Module namespace
preload = message('module-preload')
else
preload = message('docpage-preload')
Line 482 ⟶ 542:
-- @data - a table of data generated by p.makeStartBoxLinksData
--]]
local function escapeBrackets(s)
-- Escapes square brackets with HTML entities.
s = s:gsub('%[', '&#91;') -- Replace square brackets with HTML entities.
s = s:gsub('%]', '&#93;')
return s
end
 
local ret
local docTitle = data.docTitle
Line 491 ⟶ 559:
local purgeLink = makeUrlLink(title:fullUrl{action = 'purge'}, data.purgeLinkDisplay)
ret = '[%s] [%s] [%s] [%s]'
ret = escapeBrackets(ret)
ret = ret:gsub('%[', '&#91;') -- Replace square brackets with HTML entities.
ret = ret:gsub('%]', '&#93;')
ret = mw.ustring.format(ret, viewLink, editLink, historyLink, purgeLink)
else
retlocal createLink = makeUrlLink(docTitle:fullUrl{action = 'edit', preload = data.preload}, data.createLinkDisplay)
ret = '[%s]'
ret = escapeBrackets(ret)
ret = mw.ustring.format(ret, createLink)
end
return ret
Line 508 ⟶ 578:
--
-- Messages:
-- 'documentation-icon-wikitext' --> '[[File:Test Template Info-infoIcon - Version (2).pngsvg|50px|link=|alt=Documentation icon]]'
-- 'template-namespace-heading' --> 'Template documentation'
-- 'module-namespace-heading' --> 'Module documentation'
-- 'file-namespace-heading' --> 'Summary'
-- 'other-namespaces-heading' --> 'Documentation'
-- 'start-box-linkclasses' --> 'mw-editsection plainlinks'
-- 'start-box-link-id' --> 'doc_editlinks'
-- 'testcases-create-link-display' --> 'create'
--]=]
Line 547 ⟶ 615:
if headingStyle then
data.headingStyleText = headingStyle
elseif subjectSpace == 10 then
-- We are in the template or template talk namespaces.
data.headingFontWeight = 'bold'
data.headingFontSize = '125%'
else
-- 'documentation-heading'
data.headingFontSize = '150%'
data.headingClass = message('main-div-heading-class')
end
-- Data for the [view][edit][history][purge] or [create] links.
if links then
-- 'mw-editsection-like plainlinks'
data.linksClass = message('start-box-linkclasses')
data.linksIdlinksClass = message('start-box-link-idclasses')
data.links = links
end
Line 568 ⟶ 633:
-- Renders the start box html.
-- @data - a table of data generated by p.makeStartBoxData.
local sbox = htmlBuildermw.html.create('div')
sbox
-- 'documentation-startbox'
.css('padding-bottom', '3px')
:addClass(message('start-box-class'))
.css('border-bottom', '1px solid #aaa')
:newline()
.css('margin-bottom', '1ex')
.newline:tag('span')
:addClass(data.headingClass)
.tag('span')
.:cssText(data.headingStyleText)
:wikitext(data.heading)
.css('font-weight', data.headingFontWeight)
.css('font-size', data.headingFontSize)
.wikitext(data.heading)
local links = data.links
if links then
sbox.:tag('span')
.:addClass(data.linksClass)
.:attr('id', data.linksId)
.:wikitext(links)
end
return tostring(sbox)
Line 599 ⟶ 662:
-- @args - a table of arguments passed by the user
-- @env - environment table containing title objects, etc., generated with p.getEnvironment
env = env or p.getEnvironment(args)
local docTitle = env.docTitle
local content = args.content
if not content and docTitle and docTitle.exists then
local framecontent = args._content or mw.getCurrentFrame():expandTemplate{title = docTitle.prefixedText}
content = frame:preprocess('{{ ' .. docTitle.prefixedText .. ' }}')
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.contentTitle = makeInvokeFunc('_contentTitle')
 
function p._contentTitle(args, env)
env = env or p.getEnvironment(args)
local docTitle = env.docTitle
if not args.content and docTitle and docTitle.exists then
return docTitle.prefixedText
else
return ''
end
end
 
Line 622 ⟶ 697:
-- @env - environment table containing title objects, etc., generated with p.getEnvironment
--
-- Messages:
-- 'fmbox-id' --> 'documentation-meta-data'
-- 'fmbox-style' --> 'background-color: #ecfcf4'
-- 'fmbox-textstyle' --> 'font-style: italic'
--
-- The HTML is generated by the {{fmbox}} template, courtesy of [[Module:Message box]].
--]=]
-- Get environment data.
env = env or p.getEnvironment(args)
local subjectSpace = env.subjectSpace
local docTitle = env.docTitle
Line 652 ⟶ 722:
end
 
-- Assemble the argumentslink for {{fmbox}}box.
local fmargs = {}
fmargs.id = message('fmbox-id') -- Sets 'documentation-meta-data'
fmargs.image = 'none'
fmargs.style = message('fmbox-style') -- Sets 'background-color: #ecfcf4'
fmargs.textstyle = message('fmbox-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
text = text .. (p.makeDocPageBlurb(args, env) or '') -- "This documentation is transcluded from [[Foo]]."
if subjectSpace == 2 or subjectSpace == 10 or subjectSpace == 828 then
-- Add links to /sandbox and /testcases when appropriate.
-- We are in the user, template or module namespaces.
if subjectSpace == 2 or subjectSpace == 828 or subjectSpace == 10 then
-- Add sandbox and testcases links.
-- We are in the user, module or template namespaces.
-- "Editors can experiment in this template's sandbox and testcases pages."
text = text .. p.makeExperimentBlurb(args, env)
text = text .. (p.makeExperimentBlurb(args, env) or '') .. '<br />'
if not args.content and not args[1] then
-- Show"Please theadd categories text, but not if we haveto the content on the template page/doc itself,subpage."
-- Don't show this message with inline docs or with an explicitly specified doc page,
-- or if the documentation page has been specified explicitly, since then it is unclear
-- as then it is unclear where to add the categories.
text = text .. (p.makeCategoriesBlurb(args, env) or '')
end
text = text .. ' ' .. (p.makeSubpagesBlurb(args, env) or '') --"Subpages of this template"
local printBlurb = p.makePrintBlurb(args, env) -- Two-line blurb about print versions of templates.
if printBlurb then
text = text .. '<br />' .. printBlurb
Line 684 ⟶ 746:
end
end
fmargs.text = text
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 messageBox.main('fmbox\n', fmargs.. tostring(box)
end
 
Line 700 ⟶ 770:
-- 'transcluded-from-blurb' -->
-- 'The above [[Wikipedia:Template documentation|documentation]]
-- is [[WikipediaHelp:Transclusion|transcluded]] from $1.'
-- 'module-preload' --> 'Template:Documentation/preload-module-doc'
-- 'create-link-display' --> 'create'
Line 750 ⟶ 820:
-- 'mirror-edit-summary' --> 'Create sandbox version of $1'
-- 'mirror-link-display' --> 'mirror'
-- 'mirror-link-preload' --> 'Template:Documentation/mirror'
-- 'sandbox-link-display' --> 'sandbox'
-- 'testcases-link-display' --> 'testcases'
-- 'testcases-edit-link-display'--> 'edit'
-- 'module-testcases-preload' --> 'Template:Documentation/preload-module-testcases'
-- 'template-sandbox-preload' --> 'Template:Documentation/preload-sandbox'
-- 'testcases-create-link-display' --> 'create'
Line 798 ⟶ 868:
local sandboxCreateLink = makeUrlLink(sandboxCreateUrl, sandboxCreateDisplay)
local mirrorSummary = message('mirror-edit-summary', {makeWikilink(templatePage)})
local mirrorPreload = message('mirror-link-preload')
local mirrorUrl = sandboxTitle:fullUrl{action = 'edit', preload = templatePage, 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 mirrorLink = makeUrlLink(mirrorUrl, mirrorDisplay)
Line 810 ⟶ 884:
local testcasesEditDisplay = message('testcases-edit-link-display')
local testcasesEditLink = makeUrlLink(testcasesEditUrl, testcasesEditDisplay)
-- for Modules, add testcases run link if exists
testcasesLinks = testcasesLink .. ' ' .. makeToolbar(testcasesEditLink)
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
local testcasesPreload
Line 874 ⟶ 955:
pagetype = message('default-pagetype')
end
returnlocal subpagesLink = makeWikilink(
'Special:PrefixIndex/' .. templateTitle.prefixedText .. '/',
message('subpages-link-display', {pagetype})
)
return message('subpages-blurb', {subpagesLink})
end
 
Line 924 ⟶ 1,006:
-- 'testcases-subpage' --> 'testcases'
-- 'strange-usage-category' --> 'Wikipedia pages with strange ((documentation)) usage'
--
-- /testcases pages in the module namespace are not categorised, as they may have
-- {{documentation}} transcluded automatically.
--]]
local title = env.title
local subjectSpace = env.subjectSpace
if not title or not subjectSpace then
return nil
end
local subpage = title.subpageText
local ret = ''
if message('display-strange-usage-category', nil, 'boolean')
and (
and (subpage == message('doc-subpage') or subpage == message('testcases-subpage'))
subpage == message('doc-subpage')
or subjectSpace ~= 828 and subpage == message('testcases-subpage')
)
then
ret = ret .. makeCategoryLink(message('strange-usage-category'))
Retrieved from "https://civwiki.org/wiki/Module:Documentation"