Template:Documentation/doc

From Gentle Giant Home Page
Jump to navigation Jump to search

This template provides an easy, non-messy way to document a template. The method is borrowed from Wikipedia. This works properly only for templates, not for regular wiki articles. The benefits include:

  • Keeps the docs separate from the template functionality
  • Typesets all template documentation in a consistent manner
  • Automatically detects when a template is not documented and provides a link to create the docs

The method

Put your documentation in a subpage of your template, called "doc".

  1. Edit your template, say, Template:Foobar.
  2. Write your template code:
  3. Here is my fancy template definition. La la la la.
  4. End the template with <noinclude>{{documentation}}</noinclude> with no intervening whitespace:
  5. <noinclude> Here is my fancy template definition. La la la la.<noinclude>{{documentation}}</noinclude>
  6. (Optional.) If the template has no visible content, put this heading at the top:
  7. <noinclude>{{template without visible content}}</noinclude> with no intervening whitespace, like this: <noinclude>{{template without visible content}}</noinclude>Here is my fancy template definition. La la la la.<noinclude>{{documentation}}</noinclude>
  8. Save the template. It should work fine when transcluded on other pages.
  9. Write your documentation in the article Template:Foobar/doc. It will automatically get transcluded into the template to document it. If no documentation exists, your template will display a message to this effect.

Care with whitespace

When inserting the documentation template, be careful not to add whitespace unnecessarily. MediaWiki is picky about whitespace when transcluding a template.

Tips

In your documentation article, refer to the parent article as {{BASEPAGENAME}} for portability, in case the template name ever changes. This is particularly useful for demonstrating the template:

{{Documentation}}

by writing:

<nowiki>{{</nowiki>{{BASEPAGENAME}}}}