fix docstring and add check to clean_doc_string

quantumlib · Mar 16, 2024 · 7407f28 · 7407f28
1 parent 75c9ddb
commit 7407f28
Show file tree

Hide file tree

Showing 5 changed files with 22 additions and 17 deletions.
diff --git a/doc/python_api_reference_vDev.md b/doc/python_api_reference_vDev.md
@@ -2412,14 +2412,14 @@ def likeliest_error_sat_problem(
 
     Examples:
         >>> import stim
-        >>> circuit = stim.Circuit("""
+        >>> circuit = stim.Circuit('''
         ...   X_ERROR(0.1) 0
         ...   M 0
         ...   OBSERVABLE_INCLUDE(0) rec[-1]
         ...   X_ERROR(0.4) 0
         ...   M 0
         ...   DETECTOR rec[-1] rec[-2]
-        ... """)
+        ... ''')
         >>> print(circuit.likeliest_error_sat_problem(
         ...   quantization=1000
         ... ), end='')
@@ -2793,14 +2793,14 @@ def shortest_error_sat_problem(
 
     Examples:
         >>> import stim
-        >>> circuit = stim.Circuit("""
+        >>> circuit = stim.Circuit('''
         ...   X_ERROR(0.1) 0
         ...   M 0
         ...   OBSERVABLE_INCLUDE(0) rec[-1]
         ...   X_ERROR(0.4) 0
         ...   M 0
         ...   DETECTOR rec[-1] rec[-2]
-        ... """)
+        ... ''')
         >>> print(circuit.shortest_error_sat_problem(), end='')
         p wcnf 2 4 5
         1 -1 0

diff --git a/doc/stim.pyi b/doc/stim.pyi
@@ -1781,14 +1781,14 @@ class Circuit:
 
         Examples:
             >>> import stim
-            >>> circuit = stim.Circuit("""
+            >>> circuit = stim.Circuit('''
             ...   X_ERROR(0.1) 0
             ...   M 0
             ...   OBSERVABLE_INCLUDE(0) rec[-1]
             ...   X_ERROR(0.4) 0
             ...   M 0
             ...   DETECTOR rec[-1] rec[-2]
-            ... """)
+            ... ''')
             >>> print(circuit.likeliest_error_sat_problem(
             ...   quantization=1000
             ... ), end='')
@@ -2099,14 +2099,14 @@ class Circuit:
 
         Examples:
             >>> import stim
-            >>> circuit = stim.Circuit("""
+            >>> circuit = stim.Circuit('''
             ...   X_ERROR(0.1) 0
             ...   M 0
             ...   OBSERVABLE_INCLUDE(0) rec[-1]
             ...   X_ERROR(0.4) 0
             ...   M 0
             ...   DETECTOR rec[-1] rec[-2]
-            ... """)
+            ... ''')
             >>> print(circuit.shortest_error_sat_problem(), end='')
             p wcnf 2 4 5
             1 -1 0

diff --git a/glue/python/src/stim/__init__.pyi b/glue/python/src/stim/__init__.pyi
@@ -1781,14 +1781,14 @@ class Circuit:
 
         Examples:
             >>> import stim
-            >>> circuit = stim.Circuit("""
+            >>> circuit = stim.Circuit('''
             ...   X_ERROR(0.1) 0
             ...   M 0
             ...   OBSERVABLE_INCLUDE(0) rec[-1]
             ...   X_ERROR(0.4) 0
             ...   M 0
             ...   DETECTOR rec[-1] rec[-2]
-            ... """)
+            ... ''')
             >>> print(circuit.likeliest_error_sat_problem(
             ...   quantization=1000
             ... ), end='')
@@ -2099,14 +2099,14 @@ class Circuit:
 
         Examples:
             >>> import stim
-            >>> circuit = stim.Circuit("""
+            >>> circuit = stim.Circuit('''
             ...   X_ERROR(0.1) 0
             ...   M 0
             ...   OBSERVABLE_INCLUDE(0) rec[-1]
             ...   X_ERROR(0.4) 0
             ...   M 0
             ...   DETECTOR rec[-1] rec[-2]
-            ... """)
+            ... ''')
             >>> print(circuit.shortest_error_sat_problem(), end='')
             p wcnf 2 4 5
             1 -1 0

diff --git a/src/stim/circuit/circuit.pybind.cc b/src/stim/circuit/circuit.pybind.cc
@@ -2113,14 +2113,14 @@ void stim_pybind::pybind_circuit_methods(pybind11::module &, pybind11::class_<Ci
 
             Examples:
                 >>> import stim
-                >>> circuit = stim.Circuit("""
+                >>> circuit = stim.Circuit('''
                 ...   X_ERROR(0.1) 0
                 ...   M 0
                 ...   OBSERVABLE_INCLUDE(0) rec[-1]
                 ...   X_ERROR(0.4) 0
                 ...   M 0
                 ...   DETECTOR rec[-1] rec[-2]
-                ... """)
+                ... ''')
                 >>> print(circuit.shortest_error_sat_problem(), end='')
                 p wcnf 2 4 5
                 1 -1 0
@@ -2194,14 +2194,14 @@ void stim_pybind::pybind_circuit_methods(pybind11::module &, pybind11::class_<Ci
 
             Examples:
                 >>> import stim
-                >>> circuit = stim.Circuit("""
+                >>> circuit = stim.Circuit('''
                 ...   X_ERROR(0.1) 0
                 ...   M 0
                 ...   OBSERVABLE_INCLUDE(0) rec[-1]
                 ...   X_ERROR(0.4) 0
                 ...   M 0
                 ...   DETECTOR rec[-1] rec[-2]
-                ... """)
+                ... ''')
                 >>> print(circuit.likeliest_error_sat_problem(
                 ...   quantization=1000
                 ... ), end='')

diff --git a/src/stim/cmd/command_help.cc b/src/stim/cmd/command_help.cc
@@ -69,8 +69,13 @@ std::string stim::clean_doc_string(const char *c, bool allow_too_long) {
             }
             line_length++;
         }
+        const char *start_of_line = result.c_str() + result.size() - line_length - 1;
+        if (strstr(start_of_line, "\"\"\"") != nullptr) {
+            std::stringstream ss;
+            ss << "Docstring line contains \"\"\" (please use ''' instead):\n" << start_of_line << "\n";
+            throw std::invalid_argument(ss.str());
+        }
         if (!allow_too_long && line_length > 80) {
-            const char *start_of_line = result.c_str() + result.size() - line_length - 1;
             if (memcmp(start_of_line, "@signature", strlen("@signature")) != 0 &&
                 memcmp(start_of_line, "@overload", strlen("@overload")) != 0 &&
                 strstr(start_of_line, "https://") == nullptr) {