模块:Documentation

This module displays a blue box containing documentation for templates, Lua modules, or other pages. The {{documentation}} template invokes it.

Normal usage

For most uses, you should use the {{documentation}} template; please see that template's page for its usage instructions and parameters.

Use in other modules

To use this module from another Lua module, first load it with require:

local documentation = require('Module:Documentation').main

Then you can simply call it using a table of arguments.

documentation{content = 'Some documentation', ['link box'] = 'My custom link box'}

Please refer to the template documentation for usage instructions and a list of parameters.

Porting to other wikis

The module has a configuration file at Module:Documentation/config which is intended to allow easy translation and porting to other wikis. Please see the code comments in the config page for instructions. If you have any questions, or you need a feature which is not currently implemented, please leave a message at Template talk:Documentation to get the attention of a developer.

The messages that need to be customized to display a documentation template/module at the top of module pages are MediaWiki:Scribunto-doc-page-show and MediaWiki:Scribunto-doc-page-does-not-exist.

---

-- <nowiki>
local dependencyList = require( 'Module:DependencyList' )
local yn = require( 'Module:Yesno' )
local hatnote = require( 'Module:Hatnote' )._hatnote
local mbox = require( 'Module:Mbox' )._mbox
local lang = mw.getContentLanguage()
local p = {}

function p.doc( frame )
    local title = mw.title.getCurrentTitle()
    local args = frame:getParent().args
    local page = args[1] or mw.ustring.gsub( title.fullText, '/doc$', '' )
    local ret, cats, ret1, ret2, ret3
    local pageType = title.namespace == 828 and 'module' or 'template'

    local opts = frame.args;

    -- subpage header
    if title.subpageText == 'doc' then
        ret = mbox(
                'This is a documentation subpage for ' .. page .. '.',
                string.format(
                        'It contains usage information, categories, and other content that is not part of the [[' .. page .. '|original %s page]].',
                        pageType
                ),
                { icon = 'WikimediaUI-Notice.svg' }
        )

        if title.namespace == 10 then -- Template namespace
            cats = '[[Category:Template documentation|' .. title.baseText .. ']]'
            ret2 = dependencyList._main()
        elseif title.namespace == 828 then -- Module namespace
            cats = '[[Category:Module documentation|' .. title.baseText .. ']]'
            ret2 = dependencyList._main()
            ret2 = ret2 .. require('Module:Module toc').main()
        else
            cats = ''
            ret2 = ''
        end

        return tostring( ret ) .. ret2 .. cats
    end

    -- template header
    -- don't use mw.html as we aren't closing the main div tag
    ret1 = '<div class="documentation">'

    ret2 = mw.html.create( nil )
             :tag( 'div' )
             :addClass( 'documentation-header' )
             :tag( 'span' )
             :addClass( 'documentation-title' )
             :wikitext( lang:ucfirst( string.format('%s documentation', pageType) ) )
             :done()
             :tag( 'span' )
             :addClass( 'documentation-links plainlinks' )
             :wikitext(
            '[[' .. tostring( mw.uri.fullUrl( page .. '/doc', {action='view'} ) ) .. ' view]]' ..
                    '[[' .. tostring( mw.uri.fullUrl( page .. '/doc', {action='edit'} ) ) .. ' edit]]' ..
                    '[[' .. tostring( mw.uri.fullUrl( page .. '/doc', {action='history'} ) ) .. ' history]]' ..
                    '[<span class="jsPurgeLink">[' .. tostring( mw.uri.fullUrl( title.fullText, {action='purge'} ) ) .. ' purge]</span>]'
    )
             :done()
             :done()
             :tag( 'div' )
             :addClass( 'documentation-subheader' )
             :tag( 'span' )
             :addClass( 'documentation-documentation' )
             :wikitext( 'This documentation is transcluded from [[' .. page .. '/doc]]. Changes can be proposed in the talk page.' )
             :done()
             :wikitext(frame:extensionTag{ name = 'templatestyles', args = { src = 'Documentation/styles.css'} })
             :done()

    ret3 = {}

    if args.scwShared then
        --- Message box
        table.insert( ret3,
                mbox(
                        string.format(
                                "'''%s''' is [%s%s shared across] the Star Citizen Wikis.",
                                title.fullText,
                                'https://github.com/The-Star-Citizen-Wikis/SharedModules/tree/master/',
                                mw.uri.encode( title.rootText, 'PATH' )
                        ),
                        string.format(
                                'This %s is shared across the Star Citizen Wikis. Any changes should also be relayed to the GitHub repository.',
                                pageType
                        ),
                        { icon = 'WikimediaUI-ArticleDisambiguation-ltr.svg' }
                )
        )
        --- Set category
        table.insert( ret3, string.format( '[[Category:%s shared by the Star Citizen Wikis]]', lang:ucfirst( pageType )  .. 's' ) )
        --- Interlanguage link
        --- TODO: Make this into a for loop when there are more wikis
        table.insert( ret3, string.format( '[[%s:%s]]', 'de', title.fullText ) )
    end

    if args.fromWikipedia then
        table.insert( ret3,
                mbox(
                        string.format(
                                "'''%s''' is imported from [https://en.wikipedia.org/wiki/%s %s] on Wikipedia.",
                                title.fullText,
                                page,
                                page
                        ),
                        string.format(
                                'This %s is imported from the English Wikipedia. Although the visual appearance might be different, the functionality is identical. Please refer to the Wikipedia page for detailed documentation.',
                                pageType
                        ),
                        { icon = 'WikimediaUI-Logo-Wikipedia.svg' }
                )
        )
        --- Set category
        table.insert( ret3, string.format( '[[Category:%s imported from Wikipedia]]', lang:ucfirst( pageType ) .. 's' ) )
    end

    if title.namespace == 828 then
        -- Has config
        if mw.title.new( title.fullText .. '/config.json', 'Module' ).exists then
            table.insert( ret3,
                    mbox(
                            string.format(
                                    "'''%s''' loads configuration from [[%s/config.json]].",
                                    title.fullText,
                                    title.fullText
                            ),
                            'This module can be configurated from the config.json subpage.',
                            { icon='WikimediaUI-Settings.svg' }
                    )
            )
        end

        -- Has localization
        if mw.title.new( title.fullText .. '/i18n.json', 'Module' ).exists then
            table.insert( ret3,
                    mbox(
                            string.format(
                                    "'''%s''' loads messages from [[%s/i18n.json]].",
                                    title.fullText,
                                    title.fullText
                            ),
                            'This module is designed to be language-neutral. All of the messages are saved in the i18n.json subpage.',
                            { icon='WikimediaUI-Language.svg' }
                    )
            )
        end

        -- Testcase page
        if title.subpageText == 'testcases' then
            table.insert( ret3,
                    hatnote(
                            string.format( 'This is the test cases page for the module [[Module:%s]].', title.baseText ),
                            { icon='WikimediaUI-LabFlask.svg' }
                    )
            )
        end
    end

    --- Dependency list
    table.insert( ret3, dependencyList._main( nil, args.category, args.isUsed ) )

    -- Has templatestyles
    if mw.title.new( title.fullText .. '/styles.css' ).exists then
        table.insert( ret3,
                hatnote(
                        string.format(
                                "'''%s''' loads styles from [[%s/styles.css]].",
                                title.fullText,
                                title.fullText
                        ),
                        { icon='WikimediaUI-Palette.svg' }
                )
        )
    end

    --- Module stats bar
    if title.namespace == 828 then
        table.insert( ret3, '<div class="documentation-modulestats">' )

        -- Function list
        table.insert( ret3, require( 'Module:Module toc' ).main() )

        -- Unit tests
        local testcaseTitle = title.baseText .. '/testcases'
        if mw.title.new( testcaseTitle, 'Module' ).exists then
            -- There is probably a better way :P
            table.insert( ret3, frame:preprocess( '{{#invoke:' .. testcaseTitle .. '|run}}' ) )
        end

        table.insert( ret3, '</div>' )
    end

    return ret1 .. tostring( ret2 ) .. '<div class="documentation-content">' .. table.concat( ret3 )
end

return p

-- </nowiki>