From 3495a9b7e1b88a65e60d508dd398244fb534d5d1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rodrigo=20Gir=C3=A3o=20Serr=C3=A3o?=
 <5621605+rodrigogiraoserrao@users.noreply.github.com>
Date: Thu, 22 Dec 2022 11:26:04 +0000
Subject: [PATCH] Add template files for consistency.

---
 docs/css_types/_template.md            |  40 ++++++++
 docs/snippets/type_syntax/_template.md |  39 ++++++++
 docs/styles/_template.md               | 128 +++++++++++++++++++++++++
 3 files changed, 207 insertions(+)
 create mode 100644 docs/css_types/_template.md
 create mode 100644 docs/snippets/type_syntax/_template.md
 create mode 100644 docs/styles/_template.md

diff --git a/docs/css_types/_template.md b/docs/css_types/_template.md
new file mode 100644
index 000000000..c9fe058d4
--- /dev/null
+++ b/docs/css_types/_template.md
@@ -0,0 +1,40 @@
+<!-- Template file for a Textual CSS type reference page. -->
+
+# &lt;type-name&gt;
+
+<!-- Short description of the type. -->
+
+## Syntax
+
+<!--
+--8<-- "docs/snippets/type_syntax/type_name.md"
+-->
+
+## Examples
+
+### CSS
+
+<!--
+Examples should be rule-agnostic.
+Include a good variety of examples.
+If the type has many different syntaxes, cover all of them.
+Add comments when needed/if helpful.
+-->
+
+```sass
+* {
+    rule: type-value-1;
+    rule: type-value-2;
+    rule: type-value-3;
+}
+```
+
+### Python
+
+<!-- Same examples as above. -->
+
+```py
+type_name = type_value_1
+type_name = type_value_2
+type_name = type_value_3
+```
diff --git a/docs/snippets/type_syntax/_template.md b/docs/snippets/type_syntax/_template.md
new file mode 100644
index 000000000..77697f721
--- /dev/null
+++ b/docs/snippets/type_syntax/_template.md
@@ -0,0 +1,39 @@
+<!--
+This is the template file for a syntax snippet of a Textual CSS type.
+The comments below illustrate some common patterns.
+-->
+
+<!--
+For a simple type like <integer>:
+
+Describe the type in a short paragraph with an absolute link to the type page.
+E.g., “The [`<my-type>`](/css_types/my_type) type is such and such with sprinkles on top.”
+-->
+
+<!--
+For a type with many different values like <color>:
+
+Introduce the type with a link to [`<my-type>`](/css_types/my_type).
+Then, a bullet list with the variants accepted:
+
+ - you can create this type with X Y Z;
+ - you can also do A B C; and
+ - also use D E F.
+
+Consider ending with a link to the code/API that serves as ground truth for what values are accepted.
+-->
+
+<!--
+For a type that accepts specific options like <border>:
+
+Add a sentence and a table. Consider ordering values in alphabetical order if there is no other obvious ordering. See below:
+
+The [`<my-type>`](/css_types/my_type) type can take any of the following values:
+
+| Value         | Description                                   |
+|---------------|-----------------------------------------------|
+| `abc`         | Describe here.                                |
+| `other val`   | Describe this one also.                       |
+| `value three` | Please use full stops.                        |
+| `zyx`         | Describe the value without assuming any rule. |
+-->
diff --git a/docs/styles/_template.md b/docs/styles/_template.md
new file mode 100644
index 000000000..8d2e61271
--- /dev/null
+++ b/docs/styles/_template.md
@@ -0,0 +1,128 @@
+<!-- This is the template file for a CSS rule reference page. -->
+
+# Rule-name
+
+<!-- Short description of what the rule does, without syntax details or anything.
+One or two sentences is typically enough. -->
+
+## Syntax
+
+--8<-- "docs/snippets/syntax_block_start.md"
+<!-- Formal syntax description of the rule -->
+--8<-- "docs/snippets/syntax_block_end.md"
+
+<!-- Description of what the rule uses the types/values for. -->
+
+### Values
+
+<!--
+If this rule only needs one type, include it directly:
+
+--8<-- "docs/snippets/type_syntax/only_type.md"
+-->
+
+<!--
+If this rule needs two or more types:
+
+### &lt;first-type&gt;
+
+--8<-- "docs/snippets/type_syntax/first_type.md"
+
+### &lt;second-type&gt;
+
+--8<-- "docs/snippets/type_syntax/second_type.md"
+
+...
+-->
+
+### Defaults
+
+<!-- If necessary, make note of the default values here.
+Otherwise, delete this section.
+E.g., `border` contains this section. -->
+
+## Examples
+
+<!--
+Short description of the first example.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/rule.py"}
+    ```
+
+=== "rule.py"
+
+    ```py
+    --8<-- "docs/examples/styles/rule.py"
+    ```
+
+=== "rule.css"
+
+    ```scss
+    --8<-- "docs/examples/styles/rule.css"
+    ```
+-->
+
+<!--
+Short description of the second example.
+(If only one example is given, make sure the section is called "Example" and not "Examples".)
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/rule.py"}
+    ```
+
+=== "rule.py"
+
+    ```py
+    --8<-- "docs/examples/styles/rule.py"
+    ```
+
+=== "rule.css"
+
+    ```scss
+    --8<-- "docs/examples/styles/rule.css"
+    ```
+
+-->
+
+<!-- ... -->
+
+## CSS
+
+<!--
+The CSS syntax for the rule definitions.
+Include comments when relevant.
+Include all variations.
+List all values, if possible and sensible.
+
+```sass
+rule-name: value1
+rule-name: value2
+rule-name: different-syntax-value shown-here
+
+rule-name-variant: value3
+rule-name-variant: value4
+```
+
+-->
+
+## Python
+
+<!--
+The Python syntax for the rule definitions.
+Copy the same examples as the ones shown in the CSS above.
+
+If the programmatic way of setting the rule differs significantly from the CSS way, make note of that here.
+
+```py
+rule_name = value1
+rule_name = value2
+rule_name = (different_syntax_value, shown_here)
+
+rule_name_variant = value3
+rule_name_variant = value4
+```
+
+-->