Aller au contenu

Module:Documentation

Modifier les liens
Cette page fait l’objet d’une mesure de semi-protection étendue.
Une page de Wikipédia, l'encyclopédie libre.
Ceci est une version archivée de cette page, en date du 24 novembre 2019 à 17:04 et modifiée en dernier par Epok (discuter | contributions) (Mise à jour du code (voir Discussion modèle:Documentation pour le récapitulatif des modifications apportées).). Elle peut contenir des erreurs, des inexactitudes ou des contenus vandalisés non présents dans la version actuelle.

 Documentation[modifier] [purger]

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.
  • textPagebase(page) – Renvoie le nom d'une page sans son espace de noms, et sans le suffixe "/Documentation", "/Bac à sable" ou "/Test".
  • 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.
  • lienWstat(nomPage, texteLien) - Retourne un lien externe vers la page wstat de statistiques sur un modèle ou module au nom nomPage, affichant le texte texteLien.
  • notice(args, page, doc, existeDoc) – Retourne la notice de la documentation situé en bas de page.

Exemples et tests


La documentation de ce module est générée par le modèle {{Documentation module}}.
Elle est incluse depuis sa sous-page de documentation (historique).Veuillez placer les catégories sur cette page là.
Les éditeurs peuvent travailler dans le bac à sable (modifier).

-- Ce module implémente le modèle {{Méta documentation de modèle}}.

local p = {}

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

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

	--On est dans une sous-page
	local sousPage = page.subpageText
	if sousPage == 'Documentation'
	or sousPage == 'Bac à sable'
	or sousPage == 'Test' then
		return page.subjectNsText .. ':' .. page.baseText .. '/' .. souspage
	else
		return page.subjectNsText .. ':' .. page.text .. '/' .. souspage
	end
end

local function lienUrl(nomPage, titrePage, action, pagePreload)
	local argument = {['action'] = action or 'edit'}

	if pagePreload then
		argument['preload'] = 'Modèle:Documentation/Preload' .. pagePreload
	end

	return mw.ustring.format('[%s %s]', nomPage:fullUrl(argument), titrePage)
end

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

	res
		:css('margin-bottom', '1ex')
		:css('border-bottom', '1px solid #aaa')
		:css('padding-bottom', '3px')
 		:wikitext('[[Fichier: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 'Documentation')
	 		:done()

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

	if not args.contenu then
		editionLien:wikitext('[')
		if existeDoc then
			editionLien:wikitext(lienUrl(doc, 'modifier'))
		else
			if page.namespace == 828 then
				editionLien:wikitext(lienUrl(doc, 'créer', 'edit', 'Module'))
			else
				editionLien:wikitext(lienUrl(doc, 'créer', 'edit', ''))
			end
		end
		editionLien:wikitext('] ')
	end
	
	editionLien
		:wikitext('[')
		:wikitext(lienUrl(page, 'purger', 'purge'))
		:wikitext(']')

	return res
end

local function protection(page, doc, existeDoc, message)
	-- Insertion automatique du modèle de protection.
	local niveauProtection = page.protectionLevels.edit

	if niveauProtection and niveauProtection[1] then
		local tableProtection = {
			autoconfirmed = {'semiProtection', '{{%s*[Ss]emi%-protection%s*[|}]', '{{%s*[Ss]emi%-protection +longue%s*[|}]'},
			editextendedsemiprotected = {'semiProtectionEtendue', '{{%s*[Ss]emi%-protection +étendue%s*[|}]'},
			sysop = {'protection', '{{%s*[Pp]rotection%s*[|}]'},
		}
		local protection = tableProtection[niveauProtection[1]]
		if not protection then
			return ''
		end

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

		if not alreadyShown then
			if message == '' then
				message = nil
			end
			return require('Module:Protection').main({message}, 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(contenuDoc)
	local count
	repeat
		contenuDoc, count = mw.ustring.gsub(contenuDoc, '%[%[Catégorie:[^%]]+%]%][\t\r\n\f ]*$', '')
	until count == 0

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

	return contenuDoc
end

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

	if args['contenu auto haut'] then
		res:wikitext(args['contenu auto haut'])
		   :newline()
	end

	if args.contenu then
		res:newline()
		   :wikitext(args.contenu)
		   :newline()

	elseif existeDoc then
		local contenuDoc = mw.getCurrentFrame():expandTemplate{title = doc.prefixedText}
		if page.subpageText == 'Bac à sable' or page.subpageText == 'Test' then
			contenuDoc = retireBalisesCategories(contenuDoc)
		end
		res:newline()
		   :wikitext(contenuDoc)
		   :newline()

	elseif page.subpageText ~= 'Bac à sable' and page.subpageText ~= 'Test' and args['contenu facultatif'] == nil then
	
		local texteBandeau = '<b>Ce %s ne possède aucune [[Aide:Documentation de modèle|documentation]] '
			..'explicative en sous-page</b>, pas même une description succincte.<br> '
			..'Vous pouvez %s afin de documenter ce %s adéquatement.'
		if page.namespace == 828 then -- Module
			texteBandeau = texteBandeau:format(
				'module',
				lienUrl(doc, 'créer cette sous-page', 'edit', 'Module'),
				'module'
			)
		else -- Modèle
			texteBandeau = texteBandeau:format(
				'modèle',
				lienUrl(doc, 'créer cette sous-page', 'edit', ''),
				'modèle'
			)
		end
		if page.namespace == 10 then -- Modèle
			texteBandeau = texteBandeau .. '[[Catégorie:Modèle sans documentation]]'
		elseif page.namespace == 828 then -- Module
			if page.text:sub(1, 12) == 'Utilisateur:' then
				-- Pas de catégorisation pour le pseudo-namespace "Module:Utilisateur:Toto/Nom du module"
			elseif existeDoc == false then
				texteBandeau = texteBandeau .. '[[Catégorie:Module sans documentation]]'
			end
		end
		local param = {
			['icône'] = 'OOjs_UI_icon_book-ltr.svg',
			alt = 'MIT',
			style = 'width:80%;',
			texte = texteBandeau,
		}
		res:wikitext(require('Module:Bandeau')._bandeau(param))
	end

	if args['contenu auto bas'] then
		res:newline()
		   :wikitext(args['contenu auto bas'])
	end

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

	return res
end

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

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

	if args['nom modèle'] then
		local lienAide = '[[Aide:Modèle|modèle]]'
		if page.namespace == 828 then
			lienAide = '[[Aide:Module|module]]'
		end

		contenuParagraphe
			:wikitext('La [[Aide:Documentation de modèle|documentation]] de ce ')
			:wikitext(lienAide)
			:wikitext(' est générée par le modèle ')
			:wikitext(mw.getCurrentFrame():expandTemplate{title = 'm', args = {args['nom modèle']} })
			:wikitext('.<br>')
	else 
		contenuParagraphe
		:tag('span')
			:addClass('error')
			:wikitext('Erreur : le paramètre <code>nom modèle</code> n\'est pas renseigné.<br>')
	end

	if args.contenu then
		contenuParagraphe
			:wikitext('Elle est directement [[Aide:Inclusion|incluse]] dans l\'appel de ce dernier. ')
			:wikitext('Si cette page est protégée, veuillez ')
			:wikitext('transférer le contenu de la documentation vers sa ')
			:wikitext(lienUrl(doc, 'sous-page dédiée', 'edit', ''))
			:wikitext('.<br>')
	elseif existeDoc then
		contenuParagraphe
			:wikitext('Elle est [[Aide:Inclusion|incluse]] depuis ')
		
		if args['page doc'] then
			contenuParagraphe
				:wikitext('la page [[')
				:wikitext(tostring(doc))
				:wikitext(']]. ')
		else
			contenuParagraphe
				:wikitext('sa [[')
				:wikitext(tostring(doc))
				:wikitext('|sous-page de documentation]] ')
		end

		contenuParagraphe
			:tag('span')
				:css('font-size', '89%')
				:css('font-style', 'normal')
				:wikitext('(')
				:wikitext(lienUrl(doc, 'historique', 'history'))
				:wikitext(').')
				:done()

		contenuParagraphe
			:wikitext('Veuillez placer les catégories sur cette page là.<br>')
	end

	contenuParagraphe
		:wikitext('Les éditeurs peuvent travailler dans le ')

	local titrePageBacasable = nomSouspage(page, 'Bac à sable')
	local pageBacasable = mw.title.new(titrePageBacasable)

	if existePage(pageBacasable) then
		contenuParagraphe
			:wikitext('[[' .. titrePageBacasable .. '|bac à sable]]&nbsp;')
			:tag('span')
				:css('font-size', '89%')
				:css('font-style', 'normal')
				:wikitext('(')
				:wikitext(lienUrl(pageBacasable, 'modifier'))
				:wikitext(')')
	else
		local preLoad = '2'
		if page.namespace == 828 then
			preLoad = nil
		end
		contenuParagraphe
			:wikitext('bac à sable&nbsp;')
			:tag('span')
				:css('font-size', '89%')
				:css('font-style', 'normal')
				:wikitext('(')
				:wikitext(lienUrl(pageBacasable, 'créer', 'edit', preLoad))
				:wikitext(')')
	end

	if page.namespace ~= 828 then
		contenuParagraphe:wikitext(' et la page de ')

		local titrePageTest = nomSouspage(page, 'Test')
		local pageTest = mw.title.new(titrePageTest)

		if existePage(pageTest) then
			contenuParagraphe
				:wikitext('[[' .. titrePageTest .. '|test]]&nbsp;')
				:tag('span')
					:css('font-size', '89%')
					:css('font-style', 'normal')
					:wikitext('(')
					:wikitext(lienUrl(pageTest, 'modifier'))
					:wikitext(')')
		else
			contenuParagraphe
				:wikitext('test&nbsp;')
				:tag('span')
					:css('font-size', '89%')
					:css('font-style', 'normal')
					:wikitext('(')
					:wikitext(lienUrl(pageTest, 'créer', 'edit', '3'))
					:wikitext(')')
		end
	end
	contenuParagraphe:wikitext('.')

	return res
end

function p._documentation(args)
	local page = mw.title.getCurrentTitle()
	local titrePageDoc = args['page doc'] or nomSouspage(page, 'Documentation')
	local doc = mw.title.new(titrePageDoc)
	local existeDoc = existePage(doc)
	local res = mw.html.create()

	--Bandeau pour les sous-pages /Bac à sable
	if page.subpageText == 'Bac à sable' then
		res
			:tag('div')
				:css('clear', 'both')
				:done()
			:wikitext(mw.getCurrentFrame():expandTemplate{title = 'Sous-page de bac à sable'})
	end

	--Génération de la documentation
	local couleur = '#ecfcf4'
	if page.namespace == 828 then
		couleur = '#ecf0fc'
	end
	
	res
		:tag('div')
			:css('clear', 'both')
			:css('margin', '1em 0 0 0')
			:css('border', '1px solid #aaa')
			:css('background', couleur)
			:css('padding', '1em 1em 0.8em')
			:node(entete(args, page, doc, existeDoc))
			:wikitext(protection(page, doc, existeDoc, args['message protection']))
			:node(contenu(args, doc, existeDoc))
			:node(notice(args, page, doc, existeDoc))

	-- Catégorisation par défaut pour les modules sans documentation
	if page.namespace == 828 and page.subpageText ~= 'Bac à sable' and page.subpageText ~= 'Test' then
		if existeDoc == false then
			res:wikitext("[[Catégorie:Module en langage Lua]]")
		end
	end

	return tostring(res)
end

function p.documentation(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._documentation(args)
end

return p
Ce document provient de « https://fr.wikipedia.org/w/index.php?title=Module:Documentation&oldid=164809553 ».