Jump to content

Template:Documentation: Difference between revisions

no edit summary
No edit summary
No edit summary
 
Line 1: Line 1:
{{#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>}}<!--
- Documentation template
-->{{#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>}}
- A template used to show the contents of a documentation subpage
- Note: Comments (<!-- --.>) are often used to avoid unnecessary line breaks or spaces.
-->
<!--
- Pre-defined variables
--><!--
-->{{#vardefine: base page |
  {{{page|
    {{#ifeq: {{SUBPAGENAME}} | sandbox
    | {{NAMESPACE}}:{{BASEPAGENAME}}
    | {{FULLPAGENAME}}
    }}
  }}}
}}<!--


<!-- you can remove this line and everything above it if you don't see any big bold red text -->
-->{{#vardefine: current page | {{FULLPAGENAME}}}}<!--


== Description ==
-->{{#vardefine: doc page |
: '''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.'''
  {{#if: {{{page|}}}
  | {{{page}}}/doc
  | {{#if: {{{1|}}}
    | {{{1}}}
    | {{#var: base page}}/doc
    }}
  }}
}}<!--


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.
-->{{#vardefine: namespace |
  {{{demospace|{{#ifeq: {{NAMESPACE}} | {{TALKSPACE}}
  | {{SUBJECTSPACE}}
  | {{NAMESPACE}}
  }}}}}
}}<!--


==Syntax==
-->{{#vardefine: preload |
Add <code><nowiki><noinclude></nowiki>{{t|Documentation}}<nowiki></noinclude></nowiki></code> at the end of the template page.
  {{{preload|Template:Documentation/preload}}}&summary={{urlencode:Create /doc subpage for [[{{#var: base page}}]]}}&editintro=Template:Documentation/editintro-doc
}}<!--


Add <code><nowiki><noinclude></nowiki>{{t|Documentation|<documentation page>}}<nowiki></noinclude></nowiki></code> to transclude an alternative page from the /doc subpage.
-->{{#vardefine: preload-sandbox |
  {{{preload-sandbox|Template:Documentation/preload-sandbox}}}&summary={{urlencode:Create sandbox subpage for experimenting on template [[{{#var: base page}}]]}}
}}<!--


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>
-->{{#vardefine: preload-testcases |
  {{{preload-testcases|Template:Documentation/preload}}}&summary={{urlencode:Create testcases for [[{{#var: base page}}]]}}
}}<!--


For full syntax, see [[#Advanced syntax]].
-->{{#vardefine: sandbox |
  {{#if: {{{page|}}}
  | {{{page}}}/sandbox
  | {{{sandbox|{{#var: base page}}/sandbox}}}
  }}
}}<!--


==Basic usage==
-->{{#vardefine: testcases |
===On the Template page===
  {{#if: {{{page|}}}
This is the normal format when used:
  | {{{page}}}/testcases
  | {{{testcases|{{#var: base page}}/testcases}}}
  }}
}}<!--


<pre>
-->{{#vardefine: page text |
TEMPLATE CODE
  {{#switch: {{#var: namespace}}
<includeonly>Any categories to be inserted into articles by the template</includeonly>
  | {{ns:Template}} = template
<noinclude>{{Documentation}}</noinclude>
  | {{ns:Module}} = module
</pre>
  | #default = page
  }}
}}<!--


Some notes:
-->{{#vardefine: doc image |
* 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).
  {{#ifeq: {{{heading|a}}} | <!-- null -->
* 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.
  | <!-- heading is specified but empty, don't show image -->
* 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]]).
  | [[File:{{#if: {{{content|}}}
* 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).
    | Documentation_icon
    | {{#ifexist: {{#var: doc page}}
      | Documentation_icon
      | No Documentation_icon
      }}
    }}.svg|70px|link=|alt=|class=nomobile]]&nbsp;
  }}
}}<!--
-
- Sandbox header
-
-->{{#ifeq: {{SUBPAGENAMEE}} | sandbox
  | <div class="article-table"
style="padding: 1.5em; margin: auto; border: 1px solid #5556; border-bottom: 1px solid #5556; width:75%;"><!--
  -->This is a template sandbox subpage for [[{{#var: base page}}]]. <!--
  -->{{#ifexist: {{#var: testcases}}
    | See also the companion subpage for [[{{#var: testcases}}|the testcases]].
    }}<!--
--></div>
}}<!--


===On the documentation page===
--><div class="template-documentation" style="clear: both; border: 1px solid #5556; margin: 1em;"><!--
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]]).
-
- Documentation Header
-
--><div class="article-table" style="padding: 1em; margin: 0; border-bottom: 1px solid #5556;"><!--
  --><span style="font-size:1.5em">{{#var: doc image }}'''{{{heading|{{ucfirst: {{#var: page text}} }} Documentation}}}'''</span><!--
-
- Documentation page tools
-
--><span style="float: right">&#x5b;{{#if: {{{content|}}}
  | <!---->[[Special:EditPage/{{#var: current page}}|edit]] &#124; [[Special:Purge/{{#var: current page}}|purge]]
  | {{#ifexist: {{#var: doc page}}
    | <!--
    -->[[{{#var: doc page}}|view]] &#124; [[Special:EditPage/{{#var: doc page}}|edit]] &#124; [[Special:PageHistory/{{#var: doc page}}|history]] &#124; [[Special:Purge/{{#var: current page}}|purge]]
    | <!--
      -->[{{fullurl:{{FULLPAGENAMEE:{{#var: doc page}}}}|action=edit&preload={{#var: preload}} }} create] &#124; [[Special:Purge/{{#var: current page}}|purge]]
    }}
  }}]</span><!--


Normally, you will want to write something like the following on the documentation page:
--></div><!--
-
- Documentation blurb
-
--><div style="padding: 1em; padding-bottom: 0; margin: 0;">


<pre>
{{#ifeq: {{{content|a}}} | {{{content}}} | <!-- do nothing -->
== Description ==
| {{#ifexist: {{#var: doc page}}
This template is used to do something.
  | {{<!---->{{#var:doc page}}}}
  | The [[w:Help:Template documentation|documentation]] for this {{#var: page text}} does not exist. Create it at [{{fullurl:{{FULLPAGENAMEE:{{#var: doc page}}}}|action=edit&preload={{#var: preload}} }} {{#var: doc page}}].
  }}
}}<!--
-
-->{{{content|}}}


== Syntax ==
</div><!--
Type <code>{{t|templatename|param1}}</code> somewhere.
-
 
- End blurb
=== Parameters ===
-
;<code>param1</code>
-->{{#if: {{{nofooter|}}} | |
: This parameter is used to add something.
<div class="article-table" style="clear: both; padding: 0.5em; margin: 0; border-top: 1px solid #5556;"><!--
 
-
=== TemplateData ===
- The above [documentation] is
&lt;templatedata>{}</templatedata>
-
 
-->{{#if: {{{content|}}}
== Examples ==
  | <!-- do not show -->
<code>&lt;nowiki>{{templatename|input}}&lt;/nowiki></code>  
  | {{#ifexist: {{#var: doc page}}
 
    | {{#ifeq: {{SUBPAGENAME}} | sandbox
results in...
      | This is the sandbox subpage of [[{{#var: base page}}]];
 
      | The above
{{templatename|input}}
      }}&nbsp;[[w:Help:Template documentation|documentation]] is [[mw:Help:Transclusion|transcluded]] from [[{{#var: doc page}}]]. <small>([[Special:EditPage/{{#var: doc page}}|edit]] &#124; [[Special:PageHistory/{{#var: doc page}}|history]])</small><br/>
 
 
<includeonly>Any categories for the template itself</includeonly>
    | {{#ifeq: {{#var: namespace}} | {{ns:Module}}
<noinclude>[[Category:Template documentation]]</noinclude>
      | You might want to [{{fullurl:{{FULLPAGENAMEE:{{#var: doc page}}}}|action=edit&preload={{#var: preload}} }} create documentation] for this [[w:Help:Lua|Scribuntu module]]. <br/>
</pre>
      | [{{fullurl:{{FULLPAGENAMEE:{{#var: doc page}}}}|action=edit&preload={{#var: preload}} }} Create documentation] for this template. <br/>
 
      }}
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>
  - Sandbox and testcases.
{
  -
"params": {
  - NOTE: THIS WILL CREATE MANY (yes, MANY) REDLINKS (IF YOU DIDN'T MAKE THE /sandbox or /testcases PAGES). IF YOU DONT WANT THE LINKS, PLEASE REPLACE THE CODE BELOW WITH:
"1": {
  <
"label": "Custom page to transclude",
    Editors can experiment in the page's [{{fullurl: {{#var: sandbox}}}} sandbox] and [{{fullurl: {{#var: testcases}}}} testcases] pages.
"description": "A custom page to transclude, usually another documentation page",
  >
"type": "wiki-page-name"
  -
},
  --><!--
"page": {
--><!-- CHANGE START --><!--
"label": "Demo page",
-->Editors can experiment in this {{#var: page text}}'s <!--
"description": "For testing purposes",
  -
"type": "wiki-page-name"
-->{{#ifexist: {{#var: sandbox}}
},
  | [[{{#var: sandbox}}|sandbox]] <!--
"demospace": {
  --><small>(<!--
"label": "Demo namespace",
    -->[[Special:EditPage/{{#var: sandbox}}|edit]] &#124; <!--
"description": "For testing purposes; changes the internal namespace of the template",
    -->[{{fullurl: Special:ComparePages
"type": "string"
        | page1={{FULLPAGENAMEE:{{#var: base page}}}}&page2={{FULLPAGENAMEE:{{#var: current page}}}}
},
        }} diff]<!--
"preload": {
  -->)</small>
"label": "Custom documentation preload",
     
"description": "Custom documentation preload that will be used for the [create] links for the /doc subpage",
  | sandbox <small>(<!--
"type": "wiki-page-name"
  -->[{{fullurl: {{FULLPAGENAMEE:{{#var: sandbox}}}}
},
    | action=edit&preload={{#var: preload-sandbox}}
"preload-sandbox": {
    }} create] &#124; [{{fullurl: {{FULLPAGENAMEE:{{#var: sandbox}}}}
"label": "Custom preload page for /sandbox subpage",
    | action=edit&preload={{FULLPAGENAMEE:{{#var: base page}}}}
"type": "wiki-page-name"
    }} mirror]<!--
},
  -->)</small>
"preload-testcases": {
 
"label": "Custom preload page for /testcases subpage",
  }}<!--
"type": "wiki-page-name"
 
},
  --> and <!--
"sandbox": {
 
"label": "Custom /sandbox subpage",
  -->{{#ifexist: {{#var:testcases}}
"description": "Page that is used for the /sandbox link",
    | [[{{#var:testcases}}|testcases]] <small>([[Special:EditPage/{{#var: testcases}}|edit]])</small>
"type": "wiki-page-name"
   
},
    | testcases <small>(<!--
"testcases": {
    -->[{{fullurl: {{FULLPAGENAMEE:{{#var: testcases}}}}
"label": "Custom /testcases page",
        | action=edit&preload={{#var: preload-testcases}}
"description": "Page that is used for the /testcases link",
        }} create]<!--
"type": "wiki-page-name"
    -->)</small>
},
    }}<!--
"heading": {
  --> pages.<br/><!--
"label": "Custom heading text",
  --><!-- CHANGE END --><!--
"type": "string"
  -
},
  - Category addition text & subpages text.
"content": {
  -
"label": "Custom content",
  -->{{#if: {{{content|{{{1|}}}}}}
"description": "Custom inline content to add in the template. When this is added, the template does not transclude 1= or the /doc subpage",
      | <!-- Do NOT show cat text *if* documentation is inline or transcluded from a different page. -->
"type": "string"
      | {{#ifexist: {{#var: doc page}}
},
        | Add [[w:Help:categories|categories]] and [[w:Help:interwiki links|interwikis]] to the [[{{#var: doc page}}|/doc]] subpage.&nbsp;
"nofooter": {
        }}
"label": "Disable footer",
      }}<!--
"description": "Disables the footer or \"link box\" located below the documentation content.",
      -
"type": "boolean"
      -->[[Special:PrefixIndex/{{#var: current page}}|Subpages of this {{#var: page text}}]].
}
</div>
},
}}
"description": "This template is used to insert a description of a template.",
</div>
"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>