Bureaucrats, Moderators (CommentStreams), Interface administrators, Push subscription managers, Suppressors, Administrators
12,446
edits
Saintapedia:Template documentation: Difference between revisions
Jump to navigation
Jump to search
Saintapedia:Template documentation (view source)
Revision as of 03:32, 27 September 2025
, 27 Septemberno edit summary
No edit summary |
No edit summary |
||
| Line 1: | Line 1: | ||
= Saintapedia:Template Documentation = | = Saintapedia:Template Documentation = | ||
This page provides guidance for creating and maintaining documentation for all templates on Saintapedia. Templates are reusable components that standardize content presentation, simplify editing, and support dynamic data display (e.g., via Cargo tables) for topics like saints, parishes, dioceses, and Catholic demographics. Proper documentation ensures templates are easy to use and maintain. This guide explains the `{{Documentation subpage}}` template and best practices for documenting any template on the wiki. | This page provides guidance for creating and maintaining documentation for all templates on Saintapedia. Templates are reusable components that standardize content presentation, simplify editing, and support dynamic data display (e.g., via Cargo tables) for topics like saints, parishes, dioceses, and Catholic demographics. Proper documentation ensures templates are easy to use and maintain. This guide explains the `{{tlx|Documentation subpage}}` template and best practices for documenting any template on the wiki. | ||
== Purpose of Template Documentation == | == Purpose of Template Documentation == | ||
| Line 10: | Line 10: | ||
* Maintenance: Simplifying updates, especially for templates using Cargo or other extensions. | * Maintenance: Simplifying updates, especially for templates using Cargo or other extensions. | ||
== Using {{Documentation subpage}} == | == Using {{tlx|Documentation subpage}} == | ||
The `{{Documentation subpage}}` template marks a page as the documentation for a specific template. It is placed at the top of a subpage (e.g., `Template:Example/doc`) to indicate its purpose and provide navigation links. | The `{{tlx|Documentation subpage}}` template marks a page as the documentation for a specific template. It is placed at the top of a subpage (e.g., `Template:Example/doc`) to indicate its purpose and provide navigation links. | ||
* '''Usage''': | * '''Usage''': | ||
<pre>{{Documentation subpage}}</pre> | <pre>{{tlx|Documentation subpage}}</pre> | ||
Place this at the start of the documentation subpage. It displays a notice stating that the page documents a template, with links to the template, its talk page, and (if available) sandbox or testcases. | Place this at the start of the documentation subpage. It displays a notice stating that the page documents a template, with links to the template, its talk page, and (if available) sandbox or testcases. | ||
* '''Purpose''': | * '''Purpose''': | ||
| Line 20: | Line 20: | ||
* Encourages editors to discuss improvements on the template’s talk page. | * Encourages editors to discuss improvements on the template’s talk page. | ||
* Supports testing in a sandbox to avoid breaking live templates. | * Supports testing in a sandbox to avoid breaking live templates. | ||
* '''Example''': For a template named `{{Infobox saint}}`, the documentation page at `Template:Infobox saint/doc` would start with: | * '''Example''': For a template named `{{tlx|Infobox saint}}`, the documentation page at `Template:Infobox saint/doc` would start with: | ||
<pre>{{Documentation subpage}}</pre> | <pre>{{tlx|Documentation subpage}}</pre> | ||
Followed by sections explaining the template’s purpose, parameters, and usage. | Followed by sections explaining the template’s purpose, parameters, and usage. | ||
| Line 30: | Line 30: | ||
* Navigate to `Template:<TemplateName>/doc` (e.g., `Template:Infobox saint/doc`). | * Navigate to `Template:<TemplateName>/doc` (e.g., `Template:Infobox saint/doc`). | ||
* If it doesn’t exist, create the page by editing it. | * If it doesn’t exist, create the page by editing it. | ||
* Add `{{Documentation subpage}}` at the top. | * Add `{{tlx|Documentation subpage}}` at the top. | ||
2. Structure the Documentation: | 2. Structure the Documentation: | ||
Use the following standard format: | Use the following standard format: | ||
* Purpose: Describe what the template does (e.g., “Displays a standardized infobox for saint biographies”). | * Purpose: Describe what the template does (e.g., “Displays a standardized infobox for saint biographies”). | ||
* Usage: Provide the basic syntax (e.g., `{{TemplateName|parameter1|parameter2}}`). | * Usage: Provide the basic syntax (e.g., `{{tlx|TemplateName|parameter1|parameter2}}`). | ||
* Parameters: List all parameters, their purpose, and whether they are optional or required. Use a table or bullet points for clarity. | * Parameters: List all parameters, their purpose, and whether they are optional or required. Use a table or bullet points for clarity. | ||
* Examples: Show how the template renders with sample inputs. | * Examples: Show how the template renders with sample inputs. | ||
| Line 40: | Line 40: | ||
Example structure for `Template:Infobox saint/doc`: | Example structure for `Template:Infobox saint/doc`: | ||
<pre> | <pre> | ||
{{Documentation subpage}} | {{tlx|Documentation subpage}} | ||
== Purpose == | == Purpose == | ||
The {{Infobox saint}} template creates a standardized infobox for saint biographies, displaying key details like feast day, patronage, and birth/death dates. | The {{tlx|Infobox saint}} template creates a standardized infobox for saint biographies, displaying key details like feast day, patronage, and birth/death dates. | ||
== Usage == | == Usage == | ||
<pre>{{Infobox saint | <pre>{{tlx|Infobox saint | ||
| name = | | name = | ||
| feast_day = | | feast_day = | ||
| Line 57: | Line 57: | ||
== Example == | == Example == | ||
{{Infobox saint | {{tlx|Infobox saint | ||
| name = Saint Francis of Assisi | | name = Saint Francis of Assisi | ||
| feast_day = October 4 | | feast_day = October 4 | ||
| Line 71: | Line 71: | ||
</pre> | </pre> | ||
3. Link to Documentation: | 3. Link to Documentation: | ||
* Add `{{Documentation}}` to the bottom of the template page (e.g., `Template:Infobox saint`) to display the documentation subpage content. | * Add `{{tlx|Documentation}}` to the bottom of the template page (e.g., `Template:Infobox saint`) to display the documentation subpage content. | ||
* Use `<noinclude>{{Documentation}}</noinclude>` to ensure it only appears on the template page, not where the template is transcluded. | * Use `<noinclude>{{tlx|Documentation}}</noinclude>` to ensure it only appears on the template page, not where the template is transcluded. | ||
4. Use VisualEditor or Wikitext: | 4. Use VisualEditor or Wikitext: | ||
* Saintapedia supports VisualEditor for ease of use, but wikitext is recommended for precise control in template documentation. | * Saintapedia supports VisualEditor for ease of use, but wikitext is recommended for precise control in template documentation. | ||
| Line 94: | Line 94: | ||
* Cargo Query Issues: Ensure Cargo tables are defined and populated correctly. Use Cargo drilldown to test queries. | * Cargo Query Issues: Ensure Cargo tables are defined and populated correctly. Use Cargo drilldown to test queries. | ||
* VisualEditor Errors: Switch to wikitext mode if VisualEditor introduces formatting issues. | * VisualEditor Errors: Switch to wikitext mode if VisualEditor introduces formatting issues. | ||
* Documentation Not Displaying: Confirm that `{{Documentation}}` is included in the template page and that the `/doc` subpage exists. | * Documentation Not Displaying: Confirm that `{{tlx|Documentation}}` is included in the template page and that the `/doc` subpage exists. | ||
== Examples of Common Templates == | == Examples of Common Templates == | ||
Below are examples of templates you might document on Saintapedia: | Below are examples of templates you might document on Saintapedia: | ||
* Infobox Templates: `{{Infobox saint}}`, `{{Infobox parish}}` – For structured data display. | * Infobox Templates: `{{tlx|Infobox saint}}`, `{{tlx|Infobox parish}}` – For structured data display. | ||
* Navbox Templates: `{{Saints by country}}` – For navigation links grouping related content. | * Navbox Templates: `{{tlx|Saints by country}}` – For navigation links grouping related content. | ||
* Cargo Query Templates: `{{Saints by region}}` – For dynamic lists using Cargo tables. | * Cargo Query Templates: `{{tlx|Saints by region}}` – For dynamic lists using Cargo tables. | ||
* Utility Templates: `{{Cite web}}` – For consistent citation formatting. | * Utility Templates: `{{tlx|Cite web}}` – For consistent citation formatting. | ||
For each, create a `/doc` subpage with `{{Documentation subpage}}` and follow the structure outlined above. | For each, create a `/doc` subpage with `{{tlx|Documentation subpage}}` and follow the structure outlined above. | ||
== See Also == | == See Also == | ||