Module:Documentacion

En francês : Ce module implémente le modèle {{Méta documentation de modèle}}. Voir la page du modèle pour les instructions d'utilisation.

Fonctions exportables

• documentation(frame) – Fonction principale du module – à appeler avec #invoke dans un modèle – renvoyant le code HTML de la documentation.
• _documentation(args) – Fonction subsidiaire du module – à appeler avec require() dans un autre module – et renvoyant le code HTML de la documentation.

Autres fonctions

• existePage(page) – Teste si une page existe.
• nomSouspage(page, souspage) – Renvoie le nom d'une sous-page, en tenant compte des cas où l'on se trouverait déjà dans une sous-page "/Documentation", "/Bac à sable" ou "/Test".
• lienUrl(nomPage, texteLien, action, pagePreload) – Retourne un lien wikifié vers la page nomPage, affichant le texte texteLien, avec possibilité d'ajouter des query string (paramètre action) et un preload (paramètre pagePreload).
• entete(args, page, doc, existeDoc) – Construit l'entête de la documentation contenant l'image de documentation, le titre, et les liens de création/modification/purge.
• protection(page, doc, existeDoc, message) – Construit le bandeau indiquant la protection de la page le cas échéant.
• retireBalisesCategories(contenuDoc) - Permet d'ignorer les balises de catégories lors de l'inclusion d'une page de doc pour les bacs à sables.
• contenu(args, titreDoc, existeDoc) – Retourne la concaténation de la documentation en dur, sans cadre vert. C'est cette méthode qui génère la sous-page /Documentation rédigée par l'utilisateur.
• notice(args, page, doc, existeDoc) – Retourne la notice de la documentation situé en bas de page.

Exemples et tests

• Pour des exemples, voir la page de test permettant de tester diverses modifications apportées.
• Module:Documentation/Bac à sable, {{Documentation/Bac à sable}} et {{Documentation/Test}} permettent de tester diverses modifications apportées dans une version bac à sable.

---

-- Cél modulo emplèmente lo modèlo {{Mèta documentacion de modèlo}}.

local p = {}

local function egzistePage(page)
	return page and page.exists
end

local function nomSotpage(page, sotpage)
	--On n'est pas dans une sous-page
	if not page.isSubpage then
		return page.subjectNsText .. ':' .. page.text .. '/' .. sotpage
	end

	--On est dans une sous-page
	local sotPage = page.subpageText
	if sotPage == 'Documentacion'
	or sotPage == 'Bouèta de sabla'
	or sotPage == 'Èprôva' then
		return page.subjectNsText .. ':' .. page.baseText .. '/' .. sotpage
	else
		return page.subjectNsText .. ':' .. page.text .. '/' .. sotpage
	end
end

local function limUrl(nomPage, textoLim, action, pagePreload)
	local arguments = {}

	if action then
		arguments['accion'] = action
	end

	if pagePreload then
		arguments['preload'] = 'Modèlo:Documentacion/' .. pagePreload
	end

	if arguments['accion'] or arguments['preload'] then
		return mw.ustring.format('[%s %s]', nomPage:fullUrl(arguments), textoLim)
	else
		return mw.ustring.format('[[%s|%s]]', nomPage.fullText, textoLim)
	end
end

local function enteta(args, page, doc, egzisteDoc)
	local res = mw.html.create('div')

	-- Titre
	res
		:css('margin-bottom', '1ex')
		:css('border-bottom', '1px solid #aaa')
		:css('padding-bottom', '3px')
 		:wikitext('[[Fichiér:Test Template Info-Icon.svg|50px|alt=|link=]]')
	 	:tag('span')
	 		:css('font-weight', 'bold')
	 		:css('font-size', '125%')
	 		:css('vertical-align', 'middle')
	 		:wikitext(' ')
	 		:wikitext(args.titre or 'Documentacion')
	 		:done()

	-- Liens
	local edicionLim = res:tag('span')
		:addClass('mw-editsection-like plainlinks')
		:css('vertical-align', 'middle')

	if args['nion contegnu de més'] == nil then
		if not args.contegnu then
			if egzisteDoc then
				edicionLim
					:wikitext('[')
					:wikitext(limUrl(doc, 'vêre'))
					:wikitext('] ')

					:wikitext('[')
					:wikitext(limUrl(doc, 'changiér', 'edit'))
					:wikitext('] ')

					:wikitext('[')
					:wikitext(limUrl(doc, 'historico', 'history'))
					:wikitext('] ')
			else
				local pagePreload = 'Preload'
				if page.namespace == 828 then
					pagePreload = 'PreloadModule'
				end

				edicionLim
					:wikitext('[')
					:wikitext(limUrl(doc, 'fâre', 'edit', pagePreload))
					:wikitext('] ')
			end
		end
	end

	edicionLim
		:wikitext('[')
		:wikitext(limUrl(page, 'purgiér', 'purge'))
		:wikitext(']')

	return res
end

local function protection(page, doc, egzisteDoc, messajo)
	-- Insertion automatique du modèle de protection.
	local nivelProteccion = page.protectionLevels.edit

	if nivelProteccion and nivelProteccion[1] then
		local tableProtection = {
			autoconfirmed = {'miéProtèccion', '{{%s*[Mm]ié%-protèccion%s*[|}]', '{{%s*[Mm]ié%-protèccion +longe%s*[|}]'},
			editextendedsemiprotected = {'miéProtèccionÈtendua', '{{%s*[Mm]ié%-protèccion +ètendu[ae]%s*[|}]'},
			sysop = {'protèccion', '{{%s*[Pp]rotèccion%s*[|}]'},
		}
		local protection = tableProtection[nivelProteccion[1]]
		if not protection then
			return ''
		end

		local alreadyShown = false
		if egzisteDoc then
			-- Vérification qu'il n'y a pas déjà un modèle de
			-- protection dans la documentation du modèle.
			local contegnuDoc = doc:getContent()
			if contegnuDoc:match(protection[2]) or (protection[3] and contegnuDoc:match(protection[3])) then
				alreadyShown = true
			end
		end

		if not alreadyShown then
			if messajo == '' then
				messajo = nil
			end
			return require('Module:Protection').main({messajo}, protection[1], page)
		end
	end
end

-- pour les bacs à sable, on retire les balises de catégories
-- habituellement situées en "includeonly" à la fin de la documentation
local function retireBalisesCategories(contegnuDoc)
	local count
	repeat
		contegnuDoc, count = mw.ustring.gsub(contegnuDoc, '%[%[Catègorie:[^%]]+%]%][\t\r\n\f ]*$', '')
	until count == 0

	contegnuDoc, count = mw.ustring.gsub(contegnuDoc, '[\t\r\n\f ]*$', '')

	return contegnuDoc
end

local function contegnu(args, doc, egzisteDoc)
	local page = mw.title.getCurrentTitle()
	local res = mw.html.create():newline()

	-- Contenu auto haut
	if args['contegnu ôtô hiôt'] then
		res:wikitext(args['contegnu ôtô hiôt'])
		   :newline()
	end

	-- Contenu ou sous-page de doc
	if args['nion contegnu de més'] == nil then
		if args.contegnu then
			res:newline()
			   :wikitext(args.contegnu)
			   :newline()

		elseif egzisteDoc then
			local contegnuDoc = mw.getCurrentFrame():expandTemplate{title = doc.prefixedText}
			if page.subpageText == 'Bouèta de sabla' or page.subpageText == 'Èprôva' then
				contegnuDoc = retireBalisesCategories(contegnuDoc)
			end
			res:newline()
			   :wikitext(contegnuDoc)
			   :newline()

		elseif page.subpageText ~= 'Bouèta de sabla' and page.subpageText ~= 'Èprôva' and args['contegnu u chouèx'] == nil then
			local textoBenda = '<b>Cél %s at gins de [[Éde:Documentacion de modèlo|documentacion]] '
				..'èxplicativa en sot-pâge</b>, pas mémo na dèscripcion côrta.<br> '
				..'Vos pouede %s por documentar cél %s coment fôt.'
			if page.namespace == 828 then -- Module
				textoBenda = textoBenda:format(
					'modulo',
					limUrl(doc, 'fâre cela sot-pâge', 'edit', 'PreloadModule'),
					'modulo'
				)
			else -- Modèle
				textoBenda = textoBenda:format(
					'modèlo',
					limUrl(doc, 'fâre cela sot-pâge', 'edit', 'Preload'),
					'modèlo'
				)
			end
			if page.namespace == 10 then -- Modèle
				textoBenda = textoBenda .. '[[Catègorie:Modèlo sen documentacion]]'
			elseif page.namespace == 828 then -- Module
				if page.text:sub(1, 12) == 'Utilisator:' then
					-- Pas de catégorisation pour le pseudo-namespace "Module:Utilisateur:Toto/Nom du module"
				elseif egzisteDoc == false then
					textoBenda = textoBenda .. '[[Catègorie:Modulo sen documentacion]]'
				end
			end
			local param = {
				['icôna'] = 'OOjs_UI_icon_book-ltr.svg',
				alt = 'MIT',
				style = 'width:80%;',
				texte = textoBenda,
			}
			res:wikitext(require('Module:Benda')._benda(param))
		end
	end

	-- Contenu auto bas
	if args['contegnu ôtô bâs'] then
		res:newline()
		   :wikitext(args['contegnu ôtô bâs'])
	end

	res
		:tag('div')
			:css('clear', 'both')

	return res
end

local function notice(args, page, doc, egzisteDoc)
	local res = mw.html.create('div')
		:css('border-top', '1px solid #aaa')
		:css('margin', '1.5em 0 0')

	local contegnuParagrafo = res
		:tag('p')
			:addClass('plainlinks')
			:css('margin-bottom', '0')
			:css('padding-left', '1em')
			:css('font-style', 'italic')

	-- Phrase "la documentation est générée par ..."
	if args['nom modèlo'] then
		local limEde = '[[Éde:Modèlo|modèlo]]'
		if page.namespace == 828 then
			limEde = '[[Éde:Modulo|modulo]]'
		end

		contegnuParagrafo
			:wikitext('La [[Éde:Documentacion de modèlo|documentacion]] de cél ')
			:wikitext(limEde)
			:wikitext(' est fêta per lo modèlo ')
			:wikitext(mw.getCurrentFrame():expandTemplate{title = 'm', args = {args['nom modèlo']} })
			:wikitext('.<br>')
	else
		contegnuParagrafo
		:tag('span')
			:addClass('error')
			:wikitext('Fôta : lo paramètro <code>nom modèlo</code> est pas rensègnê.<br>')
	end

	-- Phrase indiquant la provenance du contenu (dans le corps ou en sous-page)
	if args['nion contegnu de més'] == nil then
		if args.contegnu then
			contegnuParagrafo
				:wikitext('El est tot drêt [[Éde:Encllusion|rapondua]] dedens l’apèl de cél dèrriér. ')
				:wikitext('Se cela pâge est protègiêe, se vos plét ')
				:wikitext('transferâd lo contegnu de la documentacion vers sa ')
				:wikitext(limUrl(doc, 'sot-pâge consacrâye', 'edit', 'Preload'))
				:wikitext('.<br>')
		elseif egzisteDoc then
			contegnuParagrafo
				:wikitext('El est [[Éde:Encllusion|rapondua]] dedens ')

			if args['pâge doc'] then
				contegnuParagrafo
					:wikitext('la pâge [[')
					:wikitext(tostring(doc))
					:wikitext(']]. ')
			else
				contegnuParagrafo
					:wikitext('sa [[')
					:wikitext(tostring(doc))
					:wikitext('|sot-pâge de documentacion]]. ')
			end

			contegnuParagrafo
				:wikitext('Se vos plét betâd les catègories sus cela pâge.<br>')
		end
	end

	-- Phrase indiquant les liens vers le bac à sable et la page de test
	contegnuParagrafo
		:wikitext('Los èditors pôvont travalyér dedens la ')

	local titroPageBouetadesabla = nomSotpage(page, 'Bouèta de sabla')
	local pageBouetadesabla = mw.title.new(titroPageBouetadesabla)

	if egzistePage(pageBouetadesabla) then
		contegnuParagrafo
			:wikitext('[[' .. titroPageBouetadesabla .. '|bouèta de sabla]]&nbsp;')
			:tag('span')
				:css('font-size', '89%')
				:css('font-style', 'normal')
				:wikitext('(')
				:wikitext(limUrl(pageBouetadesabla, 'changiér', 'edit'))
				:wikitext(')')
	else
		local pagePreload = 'Preload2'
		if page.namespace == 828 then
			pagePreload = nil
		end
		contegnuParagrafo
			:wikitext('bouèta de sabla&nbsp;')
			:tag('span')
				:css('font-size', '89%')
				:css('font-style', 'normal')
				:wikitext('(')
				:wikitext(limUrl(pageBouetadesabla, 'fâre', 'edit', pagePreload))
				:wikitext(')')
	end

	if page.namespace ~= 828 then
		contegnuParagrafo:wikitext(' et la pâge d’ ')

		local titroPageEprova = nomSotpage(page, 'Èprôva')
		local pageEprova = mw.title.new(titroPageEprova)

		if egzistePage(pageEprova) then
			contegnuParagrafo
				:wikitext('[[' .. titroPageEprova .. '|èprôva]]&nbsp;')
				:tag('span')
					:css('font-size', '89%')
					:css('font-style', 'normal')
					:wikitext('(')
					:wikitext(limUrl(pageEprova, 'changiér', 'edit'))
					:wikitext(')')
		else
			contegnuParagrafo
				:wikitext('èprôva&nbsp;')
				:tag('span')
					:css('font-size', '89%')
					:css('font-style', 'normal')
					:wikitext('(')
					:wikitext(limUrl(pageEprova, 'fâre', 'edit', 'Preload3'))
					:wikitext(')')
		end
	end
	contegnuParagrafo:wikitext('.')

	return res
end

function p._documentacion(args)
	local page = mw.title.getCurrentTitle()
	local titroPageDoc = args['pâge doc'] or nomSotpage(page, 'Documentacion')
	local doc = mw.title.new(titroPageDoc)
	local egzisteDoc = egzistePage(doc)
	local res = mw.html.create()

	--Bandeau pour les sous-pages /Bac à sable
	if page.subpageText == 'Bouèta de sabla' then
		res
			:tag('div')
				:css('clear', 'both')
				:done()
			:wikitext(mw.getCurrentFrame():expandTemplate{title = 'Sot-pâge de bouèta de sabla'})
	end

	--Génération de la documentation
	local color = '#ecfcf4'
	if page.namespace == 828 then
		color = '#ecf0fc'
	end

	res
		:tag('div')
			:css('clear', 'both')
			:css('margin', '1em 0 0 0')
			:css('border', '1px solid #aaa')
			:css('background', color)
			:css('padding', '1em 1em 0.8em')
			:node(enteta(args, page, doc, egzisteDoc))
			:wikitext(protection(page, doc, egzisteDoc, args['mèssâjo protèccion']))
			:node(contegnu(args, doc, egzisteDoc))
			:node(notice(args, page, doc, egzisteDoc))

	-- Catégorisation par défaut pour les modules sans documentation
	if page.namespace == 828 and page.subpageText ~= 'Bouèta de sabla' and page.subpageText ~= 'Èprôva' then
		if egzisteDoc == false then
			res:wikitext("[[Catègorie:Modulo en lengâjo Lua]]")
		end
	end

	return tostring(res)
end

function p.documentacion(frame)
	local args = {}
	local argsParent = frame:getParent().args

	--Paramètres vides interprétés par Lua
	for cle, val in pairs(argsParent) do
		val = mw.text.trim(val)
		if val ~= '' then
			args[cle] = val
		end
	end

	return p._documentacion(args)
end

return p