code blocks with backticks for more control on formatting

README.md

@@ -160,6 +160,7 @@ Example:
 ## Example formatting
 
 - Use indentation for examples.
+- Indent section contents using four spaces.
 - Use code blocks for example code.
 
 Example:
@@ -177,16 +178,16 @@ Example:
         Example:
             Create foo:
 
-            ```python
-            foo = Foo("example")
-            ```
+                ```python
+                foo = Foo("example")
+                ```
 
             Run engine:
 
-            ```python
-            engine = BarEngine([foo])
-            engine.run()
-            ```
+                ```python
+                engine = BarEngine([foo])
+                engine.run()
+                ```
 
 Avoid fenced code blocks inside structured sections.
 
@@ -335,10 +336,10 @@ Example:
         Example:
             Create and inspect a Foo:
 
-            ```python
-            foo = Foo("example", value=42)
-            print(foo.name)
-            ```
+                ```python
+                foo = Foo("example", value=42)
+                print(foo.name)
+                ```
         '''
     ```
 
@@ -361,13 +362,13 @@ Example:
         Example:
             Run engine:
 
-            ```python
-            foo1 = Foo("a")
-            foo2 = Foo("b")
+                ```python
+                foo1 = Foo("a")
+                foo2 = Foo("b")
 
-            engine = BarEngine([foo1, foo2])
-            engine.run()
-            ```
+                engine = BarEngine([foo1, foo2])
+                engine.run()
+                ```
         '''
     ```
 
@@ -417,12 +418,12 @@ Example:
         Example:
             Process foo:
 
-            ```python
-            foo = Foo("example", value=10)
+                ```python
+                foo = Foo("example", value=10)
 
-            result = process(foo, multiplier=2)
-            print(result)
-            ```
+                result = process(foo, multiplier=2)
+                print(result)
+                ```
         '''
     ```
 
@@ -447,19 +448,19 @@ Example:
         Example:
             Basic usage:
 
-            ```python
-            foo1 = Foo("a")
-            foo2 = Foo("b")
+                ```python
+                foo1 = Foo("a")
+                foo2 = Foo("b")
 
-            combined = combine(foo1, foo2)
-            ```
+                combined = combine(foo1, foo2)
+                ```
 
             Pipeline usage:
 
-            ```python
-            engine = BarEngine([foo1, foo2])
-            engine.run()
-            ```
+                ```python
+                engine = BarEngine([foo1, foo2])
+                engine.run()
+                ```
         '''
     ```
 

docforge/__init__.py

@@ -159,6 +159,7 @@ Example:
 ## Example formatting
 
 - Use indentation for examples.
+- Indent section contents using four spaces.
 - Use code blocks for example code.
 
 Example:
@@ -176,16 +177,16 @@ Example:
         Example:
             Create foo:
 
-            ```python
-            foo = Foo("example")
-            ```
+                ```python
+                foo = Foo("example")
+                ```
 
             Run engine:
 
-            ```python
-            engine = BarEngine([foo])
-            engine.run()
-            ```
+                ```python
+                engine = BarEngine([foo])
+                engine.run()
+                ```
 
 Avoid fenced code blocks inside structured sections.
 
@@ -334,10 +335,10 @@ Example:
         Example:
             Create and inspect a Foo:
 
-            ```python
-            foo = Foo("example", value=42)
-            print(foo.name)
-            ```
+                ```python
+                foo = Foo("example", value=42)
+                print(foo.name)
+                ```
         '''
     ```
 
@@ -360,13 +361,13 @@ Example:
         Example:
             Run engine:
 
-            ```python
-            foo1 = Foo("a")
-            foo2 = Foo("b")
+                ```python
+                foo1 = Foo("a")
+                foo2 = Foo("b")
 
-            engine = BarEngine([foo1, foo2])
-            engine.run()
-            ```
+                engine = BarEngine([foo1, foo2])
+                engine.run()
+                ```
         '''
     ```
 
@@ -416,12 +417,12 @@ Example:
         Example:
             Process foo:
 
-            ```python
-            foo = Foo("example", value=10)
+                ```python
+                foo = Foo("example", value=10)
 
-            result = process(foo, multiplier=2)
-            print(result)
-            ```
+                result = process(foo, multiplier=2)
+                print(result)
+                ```
         '''
     ```
 
@@ -446,19 +447,19 @@ Example:
         Example:
             Basic usage:
 
-            ```python
-            foo1 = Foo("a")
-            foo2 = Foo("b")
+                ```python
+                foo1 = Foo("a")
+                foo2 = Foo("b")
 
-            combined = combine(foo1, foo2)
-            ```
+                combined = combine(foo1, foo2)
+                ```
 
             Pipeline usage:
 
-            ```python
-            engine = BarEngine([foo1, foo2])
-            engine.run()
-            ```
+                ```python
+                engine = BarEngine([foo1, foo2])
+                engine.run()
+                ```
         '''
     ```