unify templates; test toc; improve docs

README.md

@@ -36,8 +36,10 @@ Options:
     -d <db>, --database <db>        Specify database location (if missing, in memory SQLite). Valid for SQL scripts.
     -o <file>, --output <file>      Specify report file (if missing, <script_name>_<date>).
     -f <format>, --format <format>  Specify report format: html (default), md.
-    -i, --interactive               Make tables interactive (search, sort, paging). Valid for HTML output.
     -a <author>, --author <author>  Specify author (if missing, user name).
+    -t <title>, --title <title>     Specify report title (if missing, script file name)
+    -i, --interactive               Make tables interactive (search, sort, paging). Valid for HTML output.
+    -c, --toc                       Generate Table of Contents
     -v, --version                   Show version and exit.
 ```
 
@@ -64,11 +66,13 @@ Note, in case your report file contains raw html chunks (such as plots or images
 
 ## Formatting and plots
 
+In produced report, code will be broken into sections. Each section ends with a statement printing some output (e.g., `print()`). You can give titles to each section by placing _magic comment_ - `#TITLE <your_section_title>` for python, `--TITLE <your_section_title>` for SQL - after line that produces output.
+
 ### Python
 
 When it comes to report formatting, there are 3 types of outputs in a Python script: Standard `<code>` block (default), HTML, or Markdown.
 
-By default _merkury_ treats any code printing some output (e.g., `print()`) as one containing code and puts it into `<code>` blocks. If your output is actually HTML or Markdown, you need to indicate that by placing a _magic comment_ after print statement in your script.
+By default _merkury_ treats any output as standard code print and puts it into `<code>` blocks. If your output is actually HTML or Markdown, you need to indicate that by placing a _magic comment_ after print statement in your script.
 
 #### HTML
 
@@ -102,7 +106,7 @@ List:
 
 ### SQL
 
-Unlike Python, there are no special formatting instructions you can specify in comments. Outputs from all queries will be formatted as a HTML table.
+Outputs from all queries will be formatted as a HTML tables.
 
 ## Acknowledgements
 

merkury/templates/template.html

@@ -52,7 +52,7 @@ <h2>Contents</h2>
     {% for chunk in chunks %}
         <div class="code-block" id="merkury-chunk-{{ chunk.number }}">
         {% if chunk.title is not none %}
-            <h3>{{ chunk.title }}</h3>
+            <h2>{{ chunk.title }}</h2>
         {% endif %}
             <details>
             <summary>In [{{ chunk.number }}]</summary>

merkury/templates/template.md

@@ -1,13 +1,29 @@
-# {{ file_name }}
+# {{ title }}
 
 ### {{ timestamp }}
 
+{% if toc %}
+## Contents
 {% for chunk in chunks %}
-\[_In_\]
+{% if chunk.title is not none %}
+{{ chunk.number }}. {{ chunk.title }}
+{% else %}
+{{ chunk.number }}. Chunk {{ chunk.number }}
+{% endif %}
+{% endfor %}
+{% endif %}
+
+{% for chunk in chunks %}
+
+{% if chunk.title is not none %}
+## {{ chunk.title }}
+{% endif %}
+
+_In_ \[{{ chunk.number }}\]
 ```{{ script_type }}
 {{ chunk.in }}
 ```
-\[_Out_\]
+_Out_ \[{{ chunk.number }}\]
 {% if chunk.html or chunk.markdown %}
 {{ chunk.out }}
 {% else %}
@@ -18,6 +34,6 @@
 ---
 {% endfor %}
 
-_Script triggered by {{ author }} on {{ timestamp }}, ran in {{ duration }}ms_
+_Script {{ file_name }} triggered by {{ author }} on {{ timestamp }}, ran in {{ duration }}ms_
 
 _Report generated with [Merkury](https://github.com/ppatrzyk/merkury) v{{ version }}._

tests/script.py

@@ -3,8 +3,10 @@
 s = "some string"
 
 print(f"Test {s}")
+#TITLE First section
 
 b = a + 5
 
 for _ in range(2):
     print("loop test")
+#TITLE Second section

tests/test_runner.py

@@ -14,9 +14,9 @@ def test_execute_python():
     expected_code = [
         (["a = 1 + 2"], ""),
         (["""s = \"some string\""""], ""),
-        (["""print(f"Test {s}")"""], "Test some string\n"),
+        (["""print(f"Test {s}")""", "#TITLE First section"], "Test some string\n"),
         (["b = a + 5"], ""),
-        (["for _ in range(2):", """    print("loop test")"""], "loop test\nloop test\n")
+        (["for _ in range(2):", """    print("loop test")""", "#TITLE Second section"], "loop test\nloop test\n")
     ]
     assert list(execute_python(PY_SCRIPT)) == expected_code