update readme and fix generate_rtd

README.md

@@ -234,7 +234,8 @@ file to mutate.
 ```bash
 gambit mutate -f benchmarks/BinaryOpMutation/BinaryOpMutation.sol
 ```
-<!-- Code output: using `pre` to avoid the Copy To Clipboard feature -->
+
+This will generate:
 <pre>
 Generated 34 mutants in 0.69 seconds
 </pre>
@@ -253,6 +254,8 @@ provides a way to randomly downsample the number of mutants with the
 ```bash
 gambit mutate -f benchmarks/BinaryOpMutation/BinaryOpMutation.sol -n 3
 ```
+
+which will generate:
 <pre>
 Generated 3 mutants in 0.15 seconds
 </pre>
@@ -266,7 +269,8 @@ Gambit outputs all of its results in `gambit_out`:
 ```bash
 tree -L 2 gambit_out
 ```
-<!-- Code output: using `pre` to avoid the Copy To Clipboard feature -->
+
+This produces:
 <pre>
 gambit_out
 ├── gambit_results.json
@@ -371,7 +375,7 @@ Here are some examples of using the `--sourceroot` option.
    ```
 
    This should output the following:
-   <!-- Code output: using `pre` to avoid the Copy To Clipboard feature -->
+
    <pre>
    Generated 1 mutants in 0.13 seconds
    1,BinaryOpMutation,benchmarks/BinaryOpMutation/BinaryOpMutation.sol,23:10, % ,*
@@ -394,7 +398,6 @@ Here are some examples of using the `--sourceroot` option.
 
    which will output:
 
-   <!-- Code output: using `pre` to avoid the Copy To Clipboard feature -->
    <pre>
    Generated 1 mutants in 0.13 seconds
    1,BinaryOpMutation,BinaryOpMutation.sol,23:10, % ,*
@@ -410,10 +413,10 @@ Here are some examples of using the `--sourceroot` option.
    ```bash
    gambit mutate -f benchmarks/BinaryOpMutation/BinaryOpMutation.sol -n 1 --sourceroot scripts
    ```
+
    This will try to find the specified file inside of `scripts`, and since it
    doesn't exist Gambit reports the error:
 
-   <!-- Code output: using `pre` to avoid the Copy To Clipboard feature -->
    <pre>
    [ERROR gambit] [!!] Illegal Configuration: Resolved filename `/Users/USER/Gambit/benchmarks/BinaryOpMutation/BinaryOpMutation.sol` is not prefixed by the derived source root /Users/USER/Gambit/scripts
    </pre>
@@ -521,7 +524,9 @@ to the `benchmarks/` directory the `"filename"` would need to be updated to
 gambit mutate -f benchmarks/BinaryOpMutation/BinaryOpMutation.sol -n 5
 tree gambit_out -L 2
 ```
-<!-- Code output: using `pre` to avoid the Copy To Clipboard feature -->
+
+which produces:
+
 <pre>
 Generated 5 mutants in 0.15 seconds
 

scripts/generate_rtd_markdown.py

@@ -81,6 +81,21 @@ def is_note_end(line: str) -> bool:
         return len(l) == 1 or l[-2] != "_"
 
 
+def is_tag(tag: str, line: str):
+    """
+    Check if a line consists
+    """
+    return line.strip() in (f"<{tag}>", f"</{tag}>")
+
+
+def is_warning_end(line: str) -> bool:
+    """
+    A warning ends when a line is ended by an underscore. We double check to
+    ensure that the line doesn't end with two underscores.
+    """
+    return is_note_end(line)
+
+
 def is_escaped_closed_comment(line: str) -> bool:
     return line.strip() == r"--\>"
 
@@ -92,7 +107,8 @@ def translate_readme_to_rtd(readme_file_path: str) -> str:
     lines2 = []
 
     suppress_start = -1  # Track if we are suppressing
-    note_start = -1  # Track if we've started a note
+    admonition_start = -1
+    admonition_start = -1  # Track if we've started a note
     emit_start = -1
     for i, line in enumerate(lines):
         # First, check if we are suppressing
@@ -105,19 +121,36 @@ def translate_readme_to_rtd(readme_file_path: str) -> str:
         if anchor is not None:
             lines2.append(anchor)
         elif "_**note:**" == line.strip().lower():
-            if note_start > -1:
+            if admonition_start > -1:
                 raise RuntimeError(
-                    f"Already in note from line {note_start + 1}, cannot start new note on line {i+1}"
+                    f"Already in note from line {admonition_start + 1}, cannot start new note on line {i+1}"
                 )
-            note_start = i
+            admonition_start = i
             lines2.append("```{note}")
         elif "_**note:**" in line.strip().lower():
             raise RuntimeError(
                 f"Illegal note start on line {i+1}: new note tags '_**Note:**' and their closing '_' must be on their own lines"
             )
 
-        elif note_start > -1 and is_note_end(line):
-            note_start = -1
+        elif admonition_start > -1 and is_note_end(line):
+            admonition_start = -1
+            lines2.append(line.rstrip().rstrip("_"))
+            lines2.append("```")
+
+        elif "_**warning:**" == line.strip().lower():
+            if admonition_start > -1:
+                raise RuntimeError(
+                    f"Already in warning from line {admonition_start + 1}, cannot start new warning on line {i+1}"
+                )
+            admonition_start = i
+            lines2.append("```{warning}")
+        elif "_**warning:**" in line.strip().lower():
+            raise RuntimeError(
+                f"Illegal warning start on line {i+1}: new warning tags '_**Warning:**' and their closing '_' must be on their own lines"
+            )
+
+        elif admonition_start > -1 and is_warning_end(line):
+            admonition_start = -1
             lines2.append(line.rstrip().rstrip("_"))
             lines2.append("```")
 
@@ -128,6 +161,10 @@ def translate_readme_to_rtd(readme_file_path: str) -> str:
                 )
             emit_start = i
 
+        elif is_tag("pre", line):
+            num_spaces = len(line) - len(line.lstrip(' '))
+            lines2.append(f"{num_spaces * ' '}```")
+
         elif line.strip() == "-->" and emit_start > -1:
             emit_start = -1
 
@@ -149,9 +186,10 @@ def translate_readme_to_rtd(readme_file_path: str) -> str:
             )
         else:
             # replace internal links
-            l = replace_internal_references(line)
-            lines2.append(l.strip("\n"))
-    return "\n".join(lines2) + "\n"
+            lines2.append(line.strip("\n"))
+    combined = "\n".join(lines2) + "\n"
+    combined = replace_internal_references(combined)
+    return combined
 
 
 def main():