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 25 avril 2022 à 03:03 et modifiée en dernier par GrandEscogriffe (discuter | contributions) (Annulation de la modification de GrandEscogriffe (d) hm ça se voit que c'est un lien externe). Elle peut contenir des erreurs, des inexactitudes ou des contenus vandalisés non présents dans la version actuelle.

 Documentation[voir] [modifier] [historique] [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

Voir les statistiques d'utilisation du module sur l'outil wstat.

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. 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 textPagebase(page)
	--On n'est pas dans une sous-page
	if not page.isSubpage then
		return page.text
	end

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

local function nomSouspage(page, souspage)
	return page.subjectNsText .. ':' .. textPagebase(page) .. '/' .. souspage
end

local function lienUrl(nomPage, texteLien, action, pagePreload)
	local arguments = {}

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

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

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

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

	-- Titre
	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()

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

	if args['aucun contenu additionnel'] == nil then
		if not args.contenu then
			if existeDoc then
				editionLien
					:wikitext('[')
					:wikitext(lienUrl(doc, 'voir'))
					:wikitext('] ')

					:wikitext('[')
					:wikitext(lienUrl(doc, 'modifier', 'edit'))
					:wikitext('] ')

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

				editionLien
					:wikitext('[')
					:wikitext(lienUrl(doc, 'créer', 'edit', pagePreload))
					:wikitext('] ')
			end
		end
	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()

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

	-- Contenu ou sous-page de doc
	if args['aucun contenu additionnel'] == nil then
		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', 'PreloadModule'),
					'module'
				)
			else -- Modèle
				texteBandeau = texteBandeau:format(
					'modèle',
					lienUrl(doc, 'créer cette sous-page', 'edit', 'Preload'),
					'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
	end

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

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

	return res
end

local function lienWstat(nomPage, texteLien)
	local nomPageNospaces = mw.ustring.gsub(nomPage, ' ', '_')
	local url = 'https://wstat.fr/template/info/' .. nomPageNospaces
	return mw.ustring.format('[%s %s]', url, texteLien)
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 contenuWstat = res
		:tag('p')
			:css('margin-bottom', '0')
			:css('padding-left', '1em')
    
    local nomWstat = textPagebase(page)
    local texteWstat = "statistiques d'utilisation"
    
	if page.namespace == 828 then
		nomWstat = 'Module:' .. nomWstat
		texteWstat = texteWstat .. ' du module'
	else
		texteWstat = texteWstat .. ' du modèle'
	end
	
	contenuWstat:wikitext('Voir les ')
				:wikitext(lienWstat(nomWstat,  texteWstat))
				:wikitext(" sur l'outil wstat.")

	local contenuParagraphe = 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è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

	-- Phrase indiquant la provenance du contenu (dans le corps ou en sous-page)
	if args['aucun contenu additionnel'] == nil then
		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', 'Preload'))
				: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
				:wikitext('Veuillez placer les catégories sur cette page-là.<br>')
		end
	end

	-- Phrase indiquant les liens vers le bac à sable et la page de test
	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', 'edit'))
				:wikitext(')')
	else
		local pagePreload = 'Preload2'
		if page.namespace == 828 then
			pagePreload = nil
		end
		contenuParagraphe
			:wikitext('bac à sable&nbsp;')
			:tag('span')
				:css('font-size', '89%')
				:css('font-style', 'normal')
				:wikitext('(')
				:wikitext(lienUrl(pageBacasable, 'créer', 'edit', pagePreload))
				: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', 'edit'))
					:wikitext(')')
		else
			contenuParagraphe
				:wikitext('test&nbsp;')
				:tag('span')
					:css('font-size', '89%')
					:css('font-style', 'normal')
					:wikitext('(')
					:wikitext(lienUrl(pageTest, 'créer', 'edit', 'Preload3'))
					: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')
			:addClass('documentation')
			: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=193139641 ».