Merge pull request #507 from Nallebeorn/master

Fix missing examples and remove broken highlighting in docs guidelines.

community/contributing/docs_writing_guidelines.rst

@@ -15,7 +15,7 @@ In summary, always try to:
 2. Use precise action verbs
 3. Avoid verbs that end in -ing
 4. Remove unnecessary adverbs and adjectives.
-5. Ban these 8 words
+5. Ban these 8 words: obvious, simple, basic, easy, actual, just, clear, and however
 6. Use explicit references
 7. Use 's to show possession
 
@@ -42,9 +42,11 @@ Use the direct voice when possible. Take the classes, methods, and
 constants you describe as the subject. It's natural to write using the
 passive voice, but it's harder to read and produces longer sentences.
 
+.. highlight:: none
+
 Passive:
 
-.. highlight:: md
+::
 
     The man **was bitten** by the dog.
 
@@ -53,11 +55,11 @@ Active:
 ::
 
     The dog bit the man.
-
+    
 
 **Don't** use the passive voice:
 
-.. highlight:: md
+::
 
     void edit_set_pivot ( Vector2 pivot )
     [...] This method **is implemented** only in some nodes that inherit Node2D.
@@ -81,7 +83,7 @@ value to a new one:
 ::
 
     void edit_set_pivot ( Vector2 pivot )
-    Set the pivot position of the 2D node to ‘pivot’ value. [...]
+    Set the pivot position of the 2D node to [code]pivot[/code] value. [...]
 
 **Do** explain what's the consequence of this "set": use precise verbs
 like ``place``, ``position``, ``rotate``, ``fade``, etc.
@@ -89,7 +91,7 @@ like ``place``, ``position``, ``rotate``, ``fade``, etc.
 ::
 
     void edit_set_pivot ( Vector2 pivot )
-    Position the node's pivot to the 'pivot' value. [...]
+    Position the node's pivot to the [code]pivot[/code] value. [...]
 
 Avoid verbs that end in -ing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -99,14 +101,14 @@ The progressive forms describe continuous actions. E.g. "is calling",
 
 **Don't** use the progressive form for instant changes.
 
-.. highlight:: md
+::
 
     Vector2 move ( Vector2 rel_vec )
     Move the body in the given direction, **stopping** if there is an obstacle. [...]
 
 **Do** use simple present, preterit or future.
 
-.. highlight:: md
+::
 
     Vector2 move ( Vector2 rel_vec )
     Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...]
@@ -129,13 +131,13 @@ add key information to the description.
 **Don't** use redundant or meaningless adverbs. Words that lengthen the
 documentation but don't add any information:
 
-.. highlight:: md
+::
 
     **Basically** a big texture [...]
 
 **Do** write short sentences in a simple, descriptive language:
 
-.. highlight:: md
+::
 
     A big texture [...]
 
@@ -162,14 +164,14 @@ easily, actually, clearly.
 **Don't** example. The banned words lengthen the description and take
 attention away from the most important info:
 
-.. highlight:: md
+::
 
     **TextureRect**
     Control frame that **simply** draws an assigned texture. It can stretch or not. It's a **simple** way to **just** show an image in a UI.
 
 **Do** remove them:
 
-.. highlight:: md
+::
 
     **TextureRect**
     [Control] node that displays a texture. The texture can stretch to the node's bounding box or stay in the center. Useful to display sprites in your UIs.
@@ -179,28 +181,28 @@ complex or frustrate them. There's nothing like a good old *it's simple*
 to make you cringe. Here's the old brief description, the first sentence
 on the Timer node's page:
 
-.. highlight:: md
+::
 
     **Timer**
     A **simple** Timer node.
 
 **Do** explain what the node does instead:
 
-.. highlight:: md
+::
 
     **Timer**
     Calls a function of your choice after a certain duration.
 
 **Don't** use "basic", it is too vague:
 
-.. highlight:: md
+::
 
     **Vector3**
     Vector class, which performs **basic** 3D vector math operations.
 
 **Do** use the brief description to offer an overview of the node:
 
-.. highlight:: md
+::
 
     **Vector3**
     Provides essential math functions to manipulate 3D vectors: cross product, normalize, rotate, etc.
@@ -213,15 +215,15 @@ Favor explicit references over implicit ones.
 **Don't** use words like "the former", "the latter", etc. They're not
 the most common in English, and they require you to check the reference.
 
-.. highlight:: md
+::
 
-    'w' and 'h' define right and bottom margins. The **latter** two resize the texture so it fits in the defined margin.
+    [code]w[/code] and [code]h[/code] define right and bottom margins. The **latter** two resize the texture so it fits in the defined margin.
 
 **Do** repeat words. They remove all ambiguity:
 
-.. highlight:: md
+::
 
-    'w' and 'h' define right and bottom margins. **'w' and 'h'** resize the texture so it fits the margin.
+    [code]w[/code] and [code]h[/code] define right and bottom margins. **[code]w[/code] and [code]h[/code]** resize the texture so it fits the margin.
 
 If you need to repeat the same variable name 3 or 4 times, you probably
 need to rephrase your description.
@@ -234,14 +236,14 @@ milk" instead.
 
 **Don't** write "of the X":
 
-.. highlight:: md
+::
 
     The region **of the AtlasTexture that is** used.
 
 **Do** use ``'s``. It lets you put the main subject at the start of the
 sentence, and keep it short:
 
-.. highlight:: md
+::
 
     The **AtlasTexture's** used region.
 
@@ -262,14 +264,14 @@ functionality, in up to 200 characters.
 
 **Don't** write tiny and vague summaries:
 
-.. highlight:: md
+::
 
     **Node2D**
     Base node for 2D system.
 
 **Do** give an overview of the node's functionality:
 
-.. highlight:: md
+::
 
     **Node2D**
     2D game object, parent of all 2D related nodes. Has a position, rotation, scale and z-index.
@@ -313,10 +315,10 @@ Also surround boolean values, variable names and methods with [code][/code].
 
 **Do** start with "if true":
 
-.. highlight:: md
+::
 
     Timer.autostart
-    If [code]true[/code] the timer will automatically start when it enters the scene tree. Default value: `false`.
+    If [code]true[/code] the timer will automatically start when it enters the scene tree. Default value: [code]false[/code].
 
 
 Use [code] around arguments