Jump to content

Template:Documentation: Difference between revisions

no edit summary
m (1 revision imported)
No edit summary
Line 1: Line 1:
<onlyinclude><includeonly><!--
{{#ifexist: Template:Documentation/preload | <!-- nothing; preload already copied --> | :<strong class="error">Please copy <nowiki>{{Documentation}}</nowiki>'s preload template from [[w:c:templates:Template:Documentation/preload]] to [[Template:Documentation/preload]]!</strong>}}<!--
-
-->{{#ifexist: Template:T | <!-- nothing; T already copied/exists --> | :<strong class="error">Please copy <nowiki>{{T}}</nowiki> from [[w:c:templates:Template:T]] to [[Template:T]]!</strong>}}<!--
- Article Header
-->{{#ifexist: Template:T/doc | <!-- nothing; T's documentation already copied/exists --> | :<strong class="error">Please copy <nowiki>{{T}}</nowiki>'s documentation from [[w:c:templates:Template:T/doc]] to [[Template:T/doc]]!</strong>}}
-
-->{{#ifeq: {{SITENAME}}|Templates Wiki||<!--
--><div style="margin:1em; padding:10px; border: 0.5px solid #c91010; border-radius:10px; background:#f001"><span class="error">'''Your wiki got a version of [[Template:Documentation]] that is only relevant to [[w:c:templates|Templates Wiki]]!''' [{{fullurl:Template:Documentation}}?action=history Click here to revert it.]</span>
For a documentation template you can use on your wiki, see [[w:c:templates:Template:Documentation (copy)|Template:Documentation (copy) on Templates Wiki]].</div>}}<!--


--><div style="text-align:center;"><span style="font-size:large;">Template information, documentation, and installation instructions.</span><br/>
<!-- you can remove this line and everything above it if you don't see any big bold red text -->
Expand the below text for usage and other information.</div>
----<!--
-
- Documentation Transclusion
-
-->{{#if: {{{installonly|}}} |<!-- Hide doc page, useful for documentation templates -->|<div style="padding:10px; border:1px solid #444c4d; clear:both; margin-bottom:0; border-bottom:unset; border-radius:10px 10px 0 0;" class="mw-collapsible article-table" data-collapsetext="Hide documentation" data-expandtext="Show documentation"><!--
- Documentation Header
-->
<span style="font-size:large;">'''Template Documentation'''</span><!--
<!--
-->:<div style="margin:0; padding:1em; border: 0.5px solid #444c4d; border-radius:10px;" class="mw-collapsible-content"><!--
-->''Note: The template above might be broken without the parameters; this is normal.''<br/><!--
- Documentation Tools
-->{{#if: {{{content|}}}
  | [{{fullurl: {{FULLPAGENAME}}|action=edit}} Edit this template] for the documentation<!--
  -
-->| {{#ifexist: {{{1|{{FULLPAGENAME}}/doc}}}
    | View, edit, or check the history of [[:{{{1|{{FULLPAGENAME}}/doc}}}|this documentation]].
    |[{{fullurl: {{{1|{{FULLPAGENAME}}/doc}}}
              |action=edit&preload=Template:Documentation/preload<!--
            -->&summary={{urlencode:Create documentation for [[{{FULLPAGENAME}}]]}}
              }} Create documentation] for this template.
    }}
    }} ([[Template:Documentation/doc|How does this work?]])<br/>Editors can experiment with this template's [{{fullurl:{{{sandbox|{{FULLPAGENAME}}/sandbox}}}
  | action=edit&redlink=1&preload=Template:Documentation/preload-sandbox<!--
  -->&summary={{urlencode:Create sandbox version of [[{{FULLPAGENAME}}]]}}
  }} sandbox] and [{{fullurl:{{{testcases|{{FULLPAGENAME}}/testcases}}}
  | action=edit&redlink=1&preload=Template:Documentation/preload-testcases<!--
  -->&summary={{urlencode:Create testcases subpage of [[{{FULLPAGENAME}}]]}}
  }} testcases].
</div>
<!--
-
--><div style="background:none;" class="mw-collapsible-content">
{{Tocright}}
{{#if:{{{content|}}}
  | {{{content}}}{{clear}}
 
  | {{#ifexist: {{{1|{{FULLPAGENAME}}/doc}}}
    | {{#if: {{{1|}}}
      |{{{{{1}}}}}
      |{{<!---->{{FULLPAGENAME}}/doc}}}}{{clear}}
    | Documentation does not exist. Create it at [{{fullurl:
              {{#if:{{{1|}}}|{{{1}}}|{{FULLPAGENAME}}/doc}}
              |action=edit&preload=Template:Documentation/preload<!--
            -->&summary={{urlencode:Create documentation for [[{{FULLPAGENAME}}]]}}<!--
            --> {{#if:{{{1|}}}|{{{1}}}|{{FULLPAGENAME}}/doc}}] [[category:templates without documentation]].
  }}<!--end if 1-->
}}
<!--end if content-->
}}
</div></div><div style="display:none;">
----
</div><!--
- Installation
-
-->}}<div style="padding:10px;border:1px solid #444c4d; margin-top:0; border-radius:0 0 10px 10px;" class="mw-collapsible article-table" data-collapsetext="Hide install instructions" data-expandtext="Show install instructions">
<span style="font-size:large;">'''Installation Instructions'''</span><!--
--><div class="mw-collapsible-content">
<!--
-
- The section for the exporting the template.
-
--><div style="margin:1em; padding:5px; background:#0121; border: 0.5px solid #36475e; border-radius:10px;clear: both;">
  {{#ifeq:{{{SPW}}}|is not relevant
    |
    <!--
    - Export links
    -->
    | :'''''[{{fullurl:Special:Export}}?link1=Template:{{PAGENAMEE}}&link2=Template:{{PAGENAMEE}}/doc<!--
    -->{{#if:{{{dep1|}}}|&link3={{{dep1}}}&link4={{{dep1}}}/doc}}<!--
    -->{{#if:{{{dep2|}}}|&link5={{{dep2}}}&link6={{{dep2}}}/doc}}<!--
    -->{{#if:{{{dep3|}}}|&link7={{{dep3}}}&link8={{{dep3}}}/doc}}<!--
    -->{{#if:{{{dep4|}}}|&link9={{{dep4}}}&link10={{{dep4}}}/doc}}<!--
    - Alt text
    --><!--
    -
    - Main Text
    -
    --> Export this template]''', then [[w:Help:Importing and exporting pages|import]] to install it.<br/><!--
    -->''Use edit summary: ''<code><nowiki>Copied from [[w:c:templates:</nowiki>{{FULLPAGENAME}}<nowiki>]]</nowiki></code>'' to properly attribute this template's editors.}}<!--
    - If compatible with vanilla MediaWiki
    -->{{#if:{{{vanilla|}}}|:''This template is compatible with vanilla MediaWiki.''}}
    <!--
    -
    - is not relevant = Should be '''NOT''' copied
    -
    -->
:{{#switch: {{{SPW|}}}
    | starter = This template is created by default after March 11, 2020. It should be in your wiki. [[Category:Starter templates]]
| is not relevant
| is not relevant to = [[File:Warning.svg|left|50px]]<!--
    -->''This template should not be copied, because it is probably not relevant to wikis other than Templates Wiki. '''You probably don't want to copy this template to your wiki.''' {{#if:{{{SPW-link|}}}|For a similar template intended to be copied, see [[Template:{{{SPW-link}}}]].''}}<!--
  -->{{#ifeq: {{SITENAME}}
        | Templates Wiki
        | [[Category:Templates Wiki templates]]
      }}
  }}
</div><!-- End Section -->
<!--
-
- Interlanguage links
-
--><!--
- French
-->{{#if:{{{fr|}}}
    |[[fr:{{{fr}}}]]
    |
  }}<!--
- Japanese
-->{{#if:{{{ja|}}}
    |[[ja:{{{ja}}}]]
    |
  }}<!--
- Turkish
-->{{#if:{{{tr|}}}
    |[[tr:{{{tr}}}]]
    |
  }}<!--
- Simplified Chinese
-->{{#if:{{{zh|}}}
    |[[zh:{{{zh}}}]]
    |
    }}
<!--
-
- Installation Instructions
-
-->
{{#ifeq: {{{SPW}}}|is not relevant |
|{{#if: {{PROTECTIONEXPIRY: edit |{{{install|{{FULLPAGENAME}}/install}}}}}
  | ''The above message will be enough for most cases; if there are additional instructions, you can see them below.''<br/><!--
  --> {{<!---->{{{install|{{FULLPAGENAME}}/install}}}}}
  | :There is no additional installation instructions for this template. If there is any, you may create it at [{{fullurl:
              {{{install|{{FULLPAGENAME}}/install}}}
              |action=edit&preload=Template:Documentation/preload-install<!--
-->}} {{{install|{{FULLPAGENAME}}/install}}}].
}}
}}
</div></div></includeonly></onlyinclude>
{{Documentation|SPW = is not relevant|SPW-link = Documentation (copy)|fr=Modèle:Documentation|ja=Template:Documentation|tr=Şablon:Belgelendirme|zh=Template:Documentation|content= This is a version of Template:Documentation customized for Templates Wiki and so not designed to be copied to other wikis.


It acts identically to the usual Template:Documentation - and should be treated identically - except for a few particular cases.
== Description ==
* <code>content = </code> should the template have just a short blurb for documentation and not need a new page for it.
: '''Note: This template requires the [[mw:Extension:Variables|variables extension]]. See [[w:Help:Extensions#Available_on_request|Help:Extensions]] on Community Central for information on how to request this.'''
* <code>installonly =</code> for documentation templates
 
* If the template '''should transclude a documentation page other than its /doc subpage,''' use <code><nowiki>{{Documentation|documentation page}}</nowiki></code>.
This template is used to insert [[w:Help:Templates|template information]], its [[w:Help:Template parameters|parameters]], and other information on a template page. More information may be found at [[w:Help:Template documentation|Help:Template documentation]] on Community Central.
*: You may also use <code><nowiki>{{Documentation|content=documentation goes here}}</nowiki></code> to include documentation without a subpage at all.
 
* If the template '''should be [[w:Help:Interlanguage links|interlanguage linked]] but at a different name,''' use <code><nowiki>{{Documentation|fr=French name|ja=Japanese name|tr=Turkish name|zh=Chinese name}}</nowiki></code>.
==Syntax==
*: You might instead create a [[w:Help:Redirect|redirect]] on the foreign-language wiki from the name used on this wiki to theirs.
Add <code><nowiki><noinclude></nowiki>{{t|Documentation}}<nowiki></noinclude></nowiki></code> at the end of the template page.
* SPW
 
** <code>SPW=is not relevant</code> - The template (such as this one) are not relevant to wikis other than Templates Wiki.
Add <code><nowiki><noinclude></nowiki>{{t|Documentation|<documentation page>}}<nowiki></noinclude></nowiki></code> to transclude an alternative page from the /doc subpage.
** <code>SPW=starter</code> - The wikis after created on March 11, 2020 by default.  
 
* <code>dep1=</code><code>dep2=</code><code>dep3=</code><code>dep4=</code> to name up to four dependency templates (include Template: prefix, no need to name /doc pages).
To add documentation inline, meaning on the main template page itself, add <code><nowiki><noinclude></nowiki>{{t|Documentation|2=content=custom inline content}}<nowiki></noinclude></nowiki></code>
}}[[Category:Documentation templates| ]]
 
For full syntax, see [[#Advanced syntax]].
 
==Basic usage==
===On the Template page===
This is the normal format when used:
 
<pre>
TEMPLATE CODE
<includeonly>Any categories to be inserted into articles by the template</includeonly>
<noinclude>{{Documentation}}</noinclude>
</pre>
 
Some notes:
* If your template is not a completed div or table, you may need to close the tags just before <code><nowiki>{{Documentation}}</nowiki></code> is inserted (within the noinclude tags).
* A line break right before <code><nowiki>{{Documentation}}</nowiki></code> can also be useful as it helps prevent the documentation template "running into" previous code.
* If for some reason you need to transclude a different page other than the documentation page (e.g. when using a group of templates with same documentation), you can use the <code>|1=</code> parameter (see [[#Syntax|Syntax]]).
* If the template documentation is rather short, you can specify documentation inline with the text, by using the <code>|content=</code> parameter (see [[#Syntax|Syntax]] again).
 
===On the documentation page===
The documentation page is usually located on the /doc subpage for a template, but a different page can be specified with the first parameter of the template (see [[#Syntax|Syntax]]).
 
Normally, you will want to write something like the following on the documentation page:
 
<pre>
== Description ==
This template is used to do something.
 
== Syntax ==
Type <code>{{t|templatename|param1}}</code> somewhere.
 
=== Parameters ===
;<code>param1</code>
: This parameter is used to add something.
 
=== TemplateData ===
&lt;templatedata>{}</templatedata>
 
== Examples ==
<code>&lt;nowiki>{{templatename|input}}&lt;/nowiki></code>  
 
results in...
 
{{templatename|input}}
 
<includeonly>Any categories for the template itself</includeonly>
<noinclude>[[Category:Template documentation]]</noinclude>
</pre>
 
Use any or all of the above description/syntax/sample output sections. You may also want to add "see also" or other sections.
 
== Advanced syntax ==
<templatedata>
{
"params": {
"1": {
"label": "Custom page to transclude",
"description": "A custom page to transclude, usually another documentation page",
"type": "wiki-page-name"
},
"page": {
"label": "Demo page",
"description": "For testing purposes",
"type": "wiki-page-name"
},
"demospace": {
"label": "Demo namespace",
"description": "For testing purposes; changes the internal namespace of the template",
"type": "string"
},
"preload": {
"label": "Custom documentation preload",
"description": "Custom documentation preload that will be used for the [create] links for the /doc subpage",
"type": "wiki-page-name"
},
"preload-sandbox": {
"label": "Custom preload page for /sandbox subpage",
"type": "wiki-page-name"
},
"preload-testcases": {
"label": "Custom preload page for /testcases subpage",
"type": "wiki-page-name"
},
"sandbox": {
"label": "Custom /sandbox subpage",
"description": "Page that is used for the /sandbox link",
"type": "wiki-page-name"
},
"testcases": {
"label": "Custom /testcases page",
"description": "Page that is used for the /testcases link",
"type": "wiki-page-name"
},
"heading": {
"label": "Custom heading text",
"type": "string"
},
"content": {
"label": "Custom content",
"description": "Custom inline content to add in the template. When this is added, the template does not transclude 1= or the /doc subpage",
"type": "string"
},
"nofooter": {
"label": "Disable footer",
"description": "Disables the footer or \"link box\" located below the documentation content.",
"type": "boolean"
}
},
"description": "This template is used to insert a description of a template.",
"paramOrder": [
"1",
"content",
"page",
"demospace",
"preload",
"preload-sandbox",
"preload-testcases",
"sandbox",
"testcases",
"heading",
"nofooter"
],
"format": "block"
}
</templatedata>
 
== Dependencies ==
; Templates
: [[Template:Documentation/preload]]
: [[Template:Documentation/preload-sandbox]]
: [[Template:Documentation/preload-testcases]]
; Images
: [[:File:Documentation_icon.svg]]
: [[:File:No_Documentation_icon.svg]]
 
<includeonly>[[Category:Documentation templates]]</includeonly><noinclude>[[Category:Template documentation]]</noinclude>