维护提醒
BWIKI 全站将于 9 月 3 日(全天)进行维护,期间无法编辑任何页面或发布新的评论。
全站通知:
模块:Documentation
刷
历
编
跳到导航
跳到搜索
local p = {}
-- Customizable strings
local i18n = {
-- 默认设置,有必要时修改
defaultDocPage = 'doc', -- 文档页后缀
defaultSandboxPage = 'sandbox', -- 沙盒页后缀
defaultTestCasePage = 'testcases', -- 测试用例页后缀
defaultPreload = '模板:Documentation/preload', -- 存储文档页标准内容的页面
defaultPreload2 = '模板:Documentation/preload2',
-- 格式字符串,不应当翻译
commonInternalLink = '[[%s]]',
commonInternalLinkPipe = '[[%s|%s]]',
commonExternalLink = '[%s]',
commonExternalLinkWithName = '[%s %s]',
commonNamespacedPage = '%s:%s',
commonNamespacedPageWithSub = '%s:%s/%s',
-- 命名空间名称,若您的语言偏爱本地化名称,请翻译,虽然翻译与否基本上不会影响实际效果
namespaceCategory = '分类',
namespaceSpecial = '特殊',
namespaceUser = '用户',
specialPurge = 'purge',
specialEdit = 'edit',
specialHistory = 'history',
-- 如果在您的语言中,类型名称在显示上有区别,请翻译
pageType_page = '页面',
pageType_template = '模板',
pageType_module = '模块',
pageType_stylesheet = '样式表',
pageType_script = '脚本',
pageType_json = 'JSON',
pageType_message = '界面信息',
-- 如果您的wiki使用不一样的链接显示方式,请修改下列内容
linkBar = mw.text.nowiki( '[ ' ) .. '%s' .. mw.text.nowiki( ' ]' ), -- 整个链接条使用的整体样式
linkFormat = '%s', -- 单个链接使用的样式
linkSeparator = mw.text.nowiki( mw.getCurrentFrame():callParserFunction( 'int:pipe-separator' ) ), -- 不同链接间的分隔符
-- 不同类型链接的显示名称,有必要时修改
linkTextPurge = mw.getCurrentFrame():callParserFunction( 'int:purge' ),
linkTextView = mw.getCurrentFrame():callParserFunction( 'int:view' ),
linkTextEdit = mw.getCurrentFrame():callParserFunction( 'int:edit' ),
linkTextHistory = mw.getCurrentFrame():callParserFunction( 'int:history_short' ),
linkTextCreate = mw.getCurrentFrame():callParserFunction( 'int:create' ),
-- p.create()中使用的字符串:使用{{doc}}或{{subst:doc}}时显示的内容
createOutputFormat = '<noinclude>%s%s</noinclude>', -- 整体格式
createSplitDocPagePrompt = '\n<!-- 请将分类链接放在文档页面 -->', -- 要创建的文档页面为独立页面时显示的字符串
createNoSubstCategory = '需要替换模板的页面', -- 使用{{doc}}时未使用替代语法所添加的追踪分类
-- p.docPage()中使用的字符串:文档页显示的内容
docPagePrompt = '当前页面是文档页面,%s被%s引入。查看[[模板:Documentation]]获取更多信息。', -- 文档页{{documentation header}}中显示的消息。参数:代码页是或不是模块时显示的词语;代码页的链接
docPagePromptWill = '会', -- 代码页为模块时使用的词语
docPagePromptShould = '会', -- 代码页不为模块时使用的词语
docPageBadDocPrompt = "<br>'''%s的文档页面质量较低或信息缺失,需要进一步修改。'''", -- 被标记为baddoc时显示的附加消息
docPageCategory = '文档页面', -- 文档页的追踪分类
-- p.page()中使用的字符串:代码页显示的内容
pageNoDocPrompt = "'''当前%s文档缺失,需要扩充。'''", -- 独立文档页不存在时显示的消息,所有参数均为页面类型
pageNoDocCategory = '文档缺失的%s', -- 没有文档页的代码页追踪分类,参数为页面类型
pageNoDocCategoryDefault = '文档缺失的页面', -- 没有文档页的代码页追踪分类(fallback)
pageBadDocPrompt = "'''%s的文档页面质量较低或信息缺失,需要进一步修改。'''\n", -- 文档页被标记为baddoc时显示的消息,参数为页面类型
pageBadDocCategory = '文档质量较低的%s', -- 文档页被标记为baddoc时的代码页追踪分类,参数为页面类型
pageBadDocCategoryDefault = '文档质量较低的页面', -- 文档页被标记为baddoc时的代码页追踪分类(fallback)
pageDocHeaderTitle = '文档页面', -- 文档页页首的标题
pageDocJumpToCode = '跳转至代码 ↴', -- 跳转至代码链接的显示文本
pageDocHeaderBottom = '上述文档的内容来自%s。', -- 文档页页首下部显示的消息
}
-- Customizable functions
local function pageCategoryHandler( category )
return i18n.commonInternalLink:format( i18n.commonNamespacedPage:format( i18n.namespaceCategory, category ) )
end
local static = require( 'Module:Static' )
if not static.Documentation then
static.Documentation = {}
end
-- Internal functions
local function getType( namespace, page )
local pageType = 'page'
if namespace == 'Template' then
pageType = 'template'
elseif namespace == 'Module' then
pageType = 'module'
elseif page.fullText:gsub( '/' .. i18n.defaultDocPage .. '$', '' ):find( '%.css$' ) then
pageType = 'stylesheet'
elseif page.fullText:gsub( '/' .. i18n.defaultDocPage .. '$', '' ):find( '%.js$' ) then
pageType = 'script'
elseif page.fullText:gsub( '/' .. i18n.defaultDocPage .. '$', '' ):find( '%.json$' ) then
pageType = 'json'
elseif namespace == 'MediaWiki' then
pageType = 'message'
end
return pageType
end
local function getDisplayType( pageType )
return i18n[ 'pageType_' .. pageType ] or i18n.pageType_page
end
-- Exported functions
function p.create( f ) -- Creating a documentation page or transclusion through {{subst:doc}}
local args = require( 'Module:ProcessArgs' ).norm()
local page = mw.title.getCurrentTitle()
local docPage = args.page or i18n.commonNamespacedPageWithSub:format( page.nsText, page.baseText, i18n.defaultDocPage )
local out
if not args.content and tostring( page ) == docPage then
local pageType = mw.ustring.lower( args.type or getType( page.nsText, page ) )
local pageTypeDisplay = getDisplayType( pageType )
if pageType == 'module' then
out = f:preprocess( mw.title.new( i18n.defaultPreload2 ):getContent():gsub( '$1' , pageTypeDisplay ) )
else
out = f:preprocess( mw.title.new( i18n.defaultPreload ):getContent():gsub( '$1' , pageTypeDisplay ) )
end
else
local templateArgs = {}
for _, key in ipairs{ 'type', 'page', 'content', 'nodoc', 'baddoc' } do
local val = args[ key ]
if val then
if key == 'content' then val = '\n' .. val .. '\n' end
table.insert( templateArgs, key .. '=' .. val )
end
end
out = '{{documentation|' .. table.concat( templateArgs, '|' ) .. '}}'
out = out:gsub( '|}}', '}}' )
out = i18n.createOutputFormat:format( out, args.content and '' or i18n.createSplitDocPagePrompt )
end
if not mw.isSubsting() then
out = f:preprocess( out )
if not args.nocat then
out = out .. i18n.commonInternalLink:format( i18n.commonNamespacedPage:format( i18n.namespaceCategory, i18n.createNoSubstCategory ) )
end
end
return out
end
function p.docPage( f ) -- Header on the documentation page
local args = require( 'Module:ProcessArgs' ).merge( true )
local badDoc = args.baddoc
if badDoc then
static.Documentation.badDoc = '1'
end
local page = mw.title.getCurrentTitle()
local subpage = page.subpageText
if subpage == i18n.defaultSandboxPage or subpage == i18n.defaultTestCasePage then
page = page.basePageTitle
end
local docPage = mw.title.new( args.page or i18n.commonNamespacedPageWithSub:format( page.nsText, page.baseText, i18n.defaultDocPage ) )
if docPage ~= page then return end
local namespace = page.nsText
local pageType = mw.ustring.lower( args.type or getType( namespace, page ) )
local pageTypeDisplay = getDisplayType( pageType )
local body = mw.html.create( 'div' ):addClass( 'documentation' )
body
:addClass( badDoc and 'documentation-badDoc' or '' )
:tag( 'div' )
:attr( 'id', 'documentation-header-tools' )
:wikitext( i18n.linkBar:format( i18n.linkFormat:format( i18n.commonExternalLinkWithName:format( page:canonicalUrl{ action = i18n.specialPurge }, i18n.linkTextPurge ) ) ) )
:done()
:wikitext( i18n.docPagePrompt:format( pageType == 'module' and i18n.docPagePromptWill or i18n.docPagePromptShould, i18n.commonInternalLink:format( i18n.commonNamespacedPage:format( namespace, page.baseText ) ) ) )
if badDoc then
body:wikitext( i18n.docPageBadDocPrompt:format( pageTypeDisplay ) )
end
if not ( args.nocat or namespace == i18n.namespaceUser ) then
body:wikitext( i18n.commonInternalLink:format( i18n.commonNamespacedPage:format( i18n.namespaceCategory, i18n.docPageCategory ) ) )
end
return tostring( body )
end
function p.page( f ) -- Wrapper around the documentation on the main page
-- mw.text.trim uses mw.ustring.gsub, which silently fails on large strings
local function trim( s )
return ( s:gsub( '^[\t\r\n\f ]+', '' ):gsub( '[\t\r\n\f ]+$', '' ) )
--return string.gsub( s, '^[\t\r\n\f ]*(.-)[\t\r\n\f ]*$', '%1' )
end
local args = require( 'Module:ProcessArgs' ).merge( true )
local page = mw.title.getCurrentTitle()
local subpage = page.subpageText
if subpage == i18n.defaultSandboxPage or subpage == i18n.defaultTestCasePage then
page = page.basePageTitle
end
local namespace = page.nsText
local docText = trim( args.content or '' )
if docText == '' then docText = nil end
local docPage
local noDoc
if docText then
docPage = page
else
docPage = mw.title.new( args.page or i18n.commonNamespacedPageWithSub:format( namespace, page.text, i18n.defaultDocPage ) )
noDoc = args.nodoc or not docPage.exists
end
local badDoc = args.baddoc
local pageType = mw.ustring.lower( args.type or getType( namespace, page ) )
local pageTypeDisplay = getDisplayType( pageType )
if not docText and not noDoc then
docText = trim( f:expandTemplate{ title = ':' .. docPage.fullText } )
if static.Documentation.badDoc and static.Documentation.badDoc == '1' then
badDoc = 1
end
if docText == '' then
docText = nil
noDoc = 1
end
end
if docText then
docText = '\n' .. docText .. '\n'
end
local docClass = ''
local message
local category
if noDoc then
docClass = 'documentation-noDoc'
message = i18n.pageNoDocPrompt:format( pageTypeDisplay )
if not ( args.nocat or namespace == i18n.namespaceUser ) then
category = i18n.pageNoDocCategory:format( pageTypeDisplay )
if not mw.title.new( i18n.commonNamespacedPage:format( i18n.namespaceCategory, category ) ).exists then
category = i18n.pageNoDocCategoryDefault
end
end
elseif badDoc then
docClass = 'documentation-badDoc'
message = i18n.pageBadDocPrompt:format( pageTypeDisplay )
if not ( args.nocat or namespace == i18n.namespaceUser ) then
category = i18n.pageBadDocCategory:format( pageTypeDisplay )
if not mw.title.new( i18n.commonNamespacedPage:format( i18n.namespaceCategory, category ) ).exists then
category = i18n.pageBadDocCategoryDefault
end
end
end
-- Generates the link bar
local links = mw.html.create( 'span' )
:attr( 'id', 'documentation-header-tools' )
local linkList = {}
if not noDoc then
if page ~= docPage then
table.insert( linkList, i18n.linkFormat:format( i18n.commonExternalLinkWithName:format( docPage:canonicalUrl(), i18n.linkTextView ) ) )
end
table.insert( linkList, i18n.linkFormat:format( i18n.commonExternalLinkWithName:format( docPage:canonicalUrl{ action = i18n.specialEdit }, i18n.linkTextEdit ) ) )
table.insert( linkList, i18n.linkFormat:format( i18n.commonExternalLinkWithName:format( docPage:canonicalUrl{ action = i18n.specialHistory }, i18n.linkTextHistory ) ) )
else
if pageType == 'module' then
table.insert( linkList, i18n.linkFormat:format( i18n.commonExternalLinkWithName:format( docPage:canonicalUrl{ action = 'edit', preload = i18n.defaultPreload2, preloadparams = pageTypeDisplay }, i18n.linkTextCreate ) ) )
else
table.insert( linkList, i18n.linkFormat:format( i18n.commonExternalLinkWithName:format( docPage:canonicalUrl{ action = 'edit', preload = i18n.defaultPreload, preloadparams = pageTypeDisplay }, i18n.linkTextCreate ) ) )
end
end
table.insert( linkList, i18n.linkFormat:format( i18n.commonExternalLinkWithName:format( docPage:canonicalUrl{ action = i18n.specialPurge }, i18n.linkTextPurge ) ) )
links:wikitext( i18n.linkBar:format( table.concat( linkList, i18n.linkSeparator ) ) )
local body = mw.html.create( 'div' ):addClass( 'documentation' )
body
:addClass( docClass )
local header = mw.html.create( 'div' )
:addClass( 'documentation-header-top' )
header
:node( links )
:tag( 'span' )
:addClass( 'documentation-header-title' )
:wikitext( i18n.pageDocHeaderTitle )
local codePages = {
module = true,
stylesheet = true,
script = true,
}
if not noDoc and codePages[ pageType ] then
header
:tag( 'span' )
:attr( 'id', 'documentation-jump-to-code' )
:wikitext( i18n.commonInternalLinkPipe:format( '#the-code', i18n.pageDocJumpToCode ) )
end
body
:node( header ):done()
:wikitext( message )
:wikitext( docText )
if not noDoc and page ~= docPage then
body
:tag( 'div' )
:addClass( 'documentation-header-bottom' )
:node( links )
:wikitext( i18n.pageDocHeaderBottom:format( i18n.commonInternalLink:format( docPage.fullText ) ) )
end
if category then
body:wikitext( pageCategoryHandler( category ) )
end
local anchor = ''
if not noDoc and pageType ~= 'template' and pageType ~= 'message' then
anchor = mw.html.create( 'div' ):attr( 'id', 'the-code' )
end
return tostring( body ) .. tostring( anchor )
end
return p