Start to create a real documentation

Author: sfauvel

docs/test_demo_with_approvals.approved.adoc

@@ -1,9 +1,8 @@
 = Demo with approvals
 This file is an example of using doc as test with pytest.
 
-include::test_demo_with_approvals.test_first_chapter.approved.adoc[leveloffset=+1]
-include::test_demo_with_approvals.test_second_chapter.approved.adoc[leveloffset=+1]
-include::test_demo_with_approvals.test_third_chapter.approved.adoc[leveloffset=+1]
+include::test_demo_with_approvals.test_simple_chapter.approved.adoc[leveloffset=+1]
+include::test_demo_with_approvals.test_using_doc_string.approved.adoc[leveloffset=+1]
 include::test_demo_with_approvals.test_chapter_with_parameters_Arg_A_.approved.adoc[leveloffset=+1]
 include::test_demo_with_approvals.test_chapter_with_parameters_Arg_B_.approved.adoc[leveloffset=+1]
 include::test_demo_with_approvals.TestClassDemo.approved.adoc[leveloffset=+1]

docs/test_demo_with_approvals.test_first_chapter.approved.adoc

@@ -0,0 +1,19 @@
+= Simple chapter
+
+
+You can write in your test the information you want to see in your documentation.
+
+.Code use to generate this chapter
+[%collapsible]
+====
+[source,python,indent=0]
+----
+
+def test_simple_chapter(request, doc):
+    doc.write(textwrap.dedent("""
+        You can write in your test the information you want to see in your documentation.
+        """))
+
+
+----
+====

docs/test_demo_with_approvals.test_second_chapter.approved.adoc

@@ -0,0 +1,25 @@
+= Using doc string
+
+The description of the chapter can be done using Python docstring.
+
+
+This doc string is placed in the document just under the title and before the text added within the test function.
+
+.Code use to generate this chapter
+[%collapsible]
+====
+[source,python,indent=0]
+----
+
+def test_using_doc_string(request, doc):
+    """
+    The description of the chapter can be done using Python docstring.
+    """
+
+    doc.write(textwrap.dedent("""
+        This doc string is placed in the document just under the title and before the text added within the test function.
+        """))
+
+
+----
+====

docs/test_demo_with_approvals.test_simple_chapter.approved.adoc

@@ -14,4 +14,4 @@ def pytest_runtest_makereport(item, call):
         if doc_fixture_name in item.funcargs:
             doc = item.funcargs[doc_fixture_name]
             if isinstance(doc, DocAsTest):
-                doc.write(f"Exception executing test:\n----\n{rep.longreprtext}\n----\n")
+                doc.write(f"\n********************\nException executing test:\n----\n{rep.longreprtext}\n----\n")

docs/test_demo_with_approvals.test_third_chapter.approved.adoc

@@ -1,31 +1,53 @@
 """
 This file is an example of using doc as test with pytest.
 """
+import inspect
 import os
 import pytest
+import textwrap
 from doc_as_test_pytest import DocAsTest, doc, doc_module
 
-
-
-def test_first_chapter(doc):
+class CodeExtractor:
+    def extract_code(object, tag:str):
+        return inspect.getsource(object)\
+            .split(f"# >>>{tag}")[1]\
+            .split(f"# <<<{tag}")[0]
+            
+def format_code(request, tag):
+    code = CodeExtractor.extract_code(request.module, tag)
+    return (textwrap.dedent("""\
+
+        .Code use to generate this chapter
+        [%collapsible]
+        ====
+        [source,python,indent=0]
+        ----
+        {}
+        ----
+        ====
+        """).format(code))
+
+# >>>simple_chapter
+def test_simple_chapter(request, doc):
+    doc.write(textwrap.dedent("""
+        You can write in your test the information you want to see in your documentation.
+        """))
+
+# <<<simple_chapter
+    doc.write(format_code(request, "simple_chapter"))
+
+# >>>using_doc_string
+def test_using_doc_string(request, doc):
     """
-    The description of the chapter can be done with docstring.
+    The description of the chapter can be done using Python docstring.
     """
 
-    doc.write("You can write in your test the information you want to see in your documentation.")
-
-
-def test_second_chapter(doc):
-    doc.write("""
-The text written in the doc should provide enough information to say if the behaviour is correct.
+    doc.write(textwrap.dedent("""
+        This doc string is placed in the document just under the title and before the text added within the test function.
+        """))
 
-Generally, we found input and output. 
-    """)
-
-
-def test_third_chapter(doc):
-   
-    doc.write("Nothing new for this third chapter")
+# <<<using_doc_string
+    doc.write(format_code(request, "using_doc_string"))
 
 @pytest.mark.parametrize("param", [
     ("Arg A"),