Systematically adding // clang-format off, on around all \rst \endrst blocks.

Author: rwgk

include/pybind11/attr.h

@@ -78,6 +78,7 @@ struct arithmetic { };
 /// Mark a function for addition at the beginning of the existing overload chain instead of the end
 struct prepend { };
 
+// clang-format off
 /** \rst
     A call policy which places one or more guard variables (``Ts...``) around the function call.
 
@@ -95,7 +96,8 @@ struct prepend { };
             T scope_guard;
             return foo(args...); // forwarded arguments
         });
- \endrst */
+\endrst */
+// clang-format on
 template <typename... Ts> struct call_guard;
 
 template <> struct call_guard<> { using type = detail::void_type; };

include/pybind11/cast.h

@@ -1086,9 +1086,11 @@ arg_v arg::operator=(T &&value) const {
 template <typename /*unused*/> using arg_t = arg_v;
 
 inline namespace literals {
+// clang-format off
 /** \rst
     String literal version of `arg`
- \endrst */
+\endrst */
+// clang-format on
 constexpr arg operator"" _a(const char *name, size_t) { return arg(name); }
 } // namespace literals
 

include/pybind11/detail/common.h

@@ -281,6 +281,7 @@ extern "C" {
             return nullptr;                                                    \
         }                                                                      \
 
+// clang-format off
 /** \rst
     ***Deprecated in favor of PYBIND11_MODULE***
 
@@ -296,6 +297,7 @@ extern "C" {
             return m.ptr();
         }
 \endrst */
+// clang-format on
 #define PYBIND11_PLUGIN(name)                                                  \
     PYBIND11_DEPRECATED("PYBIND11_PLUGIN is deprecated, use PYBIND11_MODULE")  \
     static PyObject *pybind11_init();                                          \
@@ -308,6 +310,7 @@ extern "C" {
     }                                                                          \
     PyObject *pybind11_init()
 
+// clang-format off
 /** \rst
     This macro creates the entry point that will be invoked when the Python interpreter
     imports an extension module. The module name is given as the fist argument and it
@@ -329,6 +332,7 @@ extern "C" {
             });
         }
 \endrst */
+// clang-format on
 #define PYBIND11_MODULE(name, variable)                                        \
     static ::pybind11::module_::module_def                                     \
         PYBIND11_CONCAT(pybind11_module_def_, name) PYBIND11_MAYBE_UNUSED;     \

include/pybind11/embed.h

@@ -30,6 +30,7 @@
       }
 #endif
 
+// clang-format off
 /** \rst
     Add a new module to the table of builtins for the interpreter. Must be
     defined in global scope. The first macro parameter is the name of the
@@ -44,7 +45,8 @@
                 return "Hello, World!";
             });
         }
- \endrst */
+\endrst */
+// clang-format on
 #define PYBIND11_EMBEDDED_MODULE(name, variable)                                \
     static ::pybind11::module_::module_def                                      \
         PYBIND11_CONCAT(pybind11_module_def_, name);                            \
@@ -87,6 +89,7 @@ struct embedded_module {
 
 PYBIND11_NAMESPACE_END(detail)
 
+// clang-format off
 /** \rst
     Initialize the Python interpreter. No other pybind11 or CPython API functions can be
     called before this is done; with the exception of `PYBIND11_EMBEDDED_MODULE`. The
@@ -99,7 +102,8 @@ PYBIND11_NAMESPACE_END(detail)
     of throwing exceptions on errors.)
 
     .. _Python documentation: https://docs.python.org/3/c-api/init.html#c.Py_InitializeEx
- \endrst */
+\endrst */
+// clang-format on
 inline void initialize_interpreter(bool init_signal_handlers = true) {
     if (Py_IsInitialized())
         pybind11_fail("The interpreter is already running");
@@ -110,6 +114,7 @@ inline void initialize_interpreter(bool init_signal_handlers = true) {
     module_::import("sys").attr("path").cast<list>().append(".");
 }
 
+// clang-format off
 /** \rst
     Shut down the Python interpreter. No pybind11 or CPython API functions can be called
     after this. In addition, pybind11 objects must not outlive the interpreter:
@@ -144,7 +149,8 @@ inline void initialize_interpreter(bool init_signal_handlers = true) {
         in the CPython documentation. In short, not all interpreter memory may be
         freed, either due to reference cycles or user-created global data.
 
- \endrst */
+\endrst */
+// clang-format on
 inline void finalize_interpreter() {
     handle builtins(PyEval_GetBuiltins());
     const char *id = PYBIND11_INTERNALS_ID;
@@ -165,6 +171,7 @@ inline void finalize_interpreter() {
     }
 }
 
+// clang-format off
 /** \rst
     Scope guard version of `initialize_interpreter` and `finalize_interpreter`.
     This a move-only guard and only a single instance can exist.
@@ -177,7 +184,8 @@ inline void finalize_interpreter() {
             py::scoped_interpreter guard{};
             py::print(Hello, World!);
         } // <-- interpreter shutdown
- \endrst */
+\endrst */
+// clang-format on
 class scoped_interpreter {
 public:
     scoped_interpreter(bool init_signal_handlers = true) {

include/pybind11/iostream.h

@@ -135,6 +135,7 @@ class pythonbuf : public std::streambuf {
 PYBIND11_NAMESPACE_END(detail)
 
 
+// clang-format off
 /** \rst
     This a move-only guard that redirects output.
 
@@ -158,7 +159,8 @@ PYBIND11_NAMESPACE_END(detail)
             py::scoped_ostream_redirect output{std::cerr, py::module::import("sys").attr("stderr")};
             std::cout << "Hello, World!";
         }
- \endrst */
+\endrst */
+// clang-format on
 class scoped_ostream_redirect {
 protected:
     std::streambuf *old;
@@ -183,6 +185,7 @@ class scoped_ostream_redirect {
 };
 
 
+// clang-format off
 /** \rst
     Like `scoped_ostream_redirect`, but redirects cerr by default. This class
     is provided primary to make ``py::call_guard`` easier to make.
@@ -194,6 +197,7 @@ class scoped_ostream_redirect {
                           scoped_estream_redirect>());
 
 \endrst */
+// clang-format on
 class scoped_estream_redirect : public scoped_ostream_redirect {
 public:
     scoped_estream_redirect(std::ostream &costream  = std::cerr,
@@ -230,6 +234,7 @@ class OstreamRedirect {
 
 PYBIND11_NAMESPACE_END(detail)
 
+// clang-format off
 /** \rst
     This is a helper function to add a C++ redirect context manager to Python
     instead of using a C++ guard. To use it, add the following to your binding code:
@@ -256,7 +261,8 @@ PYBIND11_NAMESPACE_END(detail)
         with m.ostream_redirect(stdout=true, stderr=true):
             m.noisy_function_with_error_printing()
 
- \endrst */
+\endrst */
+// clang-format on
 inline class_<detail::OstreamRedirect>
 add_ostream_redirect(module_ m, const std::string &name = "ostream_redirect") {
     return class_<detail::OstreamRedirect>(std::move(m), name.c_str(), module_local())

include/pybind11/pybind11.h

@@ -956,11 +956,13 @@ class module_ : public object {
 #endif
     }
 
+    // clang-format off
     /** \rst
         Create Python binding for a new function within the module scope. ``Func``
         can be a plain C++ function, a function pointer, or a lambda function. For
         details on the ``Extra&& ... extra`` argument, see section :ref:`extras`.
     \endrst */
+    // clang-format on
     template <typename Func, typename... Extra>
     module_ &def(const char *name_, Func &&f, const Extra& ... extra) {
         cpp_function func(std::forward<Func>(f), name(name_), scope(*this),
@@ -971,6 +973,7 @@ class module_ : public object {
         return *this;
     }
 
+    // clang-format off
     /** \rst
         Create and return a new Python submodule with the given name and docstring.
         This also works recursively, i.e.
@@ -981,6 +984,7 @@ class module_ : public object {
             py::module_ m2 = m.def_submodule("sub", "A submodule of 'example'");
             py::module_ m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
     \endrst */
+    // clang-format on
     module_ def_submodule(const char *name, const char *doc = nullptr) {
         std::string full_name = std::string(PyModule_GetName(m_ptr))
             + std::string(".") + std::string(name);
@@ -1007,13 +1011,15 @@ class module_ : public object {
         *this = reinterpret_steal<module_>(obj);
     }
 
+    // clang-format off
     /** \rst
         Adds an object to the module using the given name.  Throws if an object with the given name
         already exists.
 
         ``overwrite`` should almost always be false: attempting to overwrite objects that pybind11 has
         established will, in most cases, break things.
     \endrst */
+    // clang-format on
     PYBIND11_NOINLINE void add_object(const char *name, handle obj, bool overwrite = false) {
         if (!overwrite && hasattr(*this, name))
             pybind11_fail("Error during initialization: multiple incompatible definitions with name \"" +
@@ -1028,12 +1034,14 @@ class module_ : public object {
     struct module_def {};
 #endif
 
+    // clang-format off
     /** \rst
         Create a new top-level module that can be used as the main module of a C extension.
 
         For Python 3, ``def`` should point to a statically allocated module_def.
         For Python 2, ``def`` can be a nullptr and is completely ignored.
     \endrst */
+    // clang-format on
     static module_ create_extension_module(const char *name, const char *doc, module_def *def) {
 #if PY_MAJOR_VERSION >= 3
         // module_def is PyModuleDef
@@ -2173,14 +2181,16 @@ inline function get_type_override(const void *this_ptr, const type_info *this_ty
 }
 PYBIND11_NAMESPACE_END(detail)
 
+// clang-format off
 /** \rst
   Try to retrieve a python method by the provided name from the instance pointed to by the this_ptr.
 
   :this_ptr: The pointer to the object the overridden method should be retrieved for. This should be
              the first non-trampoline class encountered in the inheritance chain.
   :name: The name of the overridden Python method to retrieve.
   :return: The Python method by this name from the object or an empty function wrapper.
- \endrst */
+\endrst */
+// clang-format on
 template <class T> function get_override(const T *this_ptr, const char *name) {
     auto tinfo = detail::get_type_info(typeid(T));
     return tinfo ? detail::get_type_override(this_ptr, tinfo, name) : function();
@@ -2200,6 +2210,7 @@ template <class T> function get_override(const T *this_ptr, const char *name) {
         } \
     } while (false)
 
+// clang-format off
 /** \rst
     Macro to populate the virtual method in the trampoline class. This macro tries to look up a method named 'fn'
     from the Python side, deals with the :ref:`gil` and necessary argument conversions to call this method and return
@@ -2217,22 +2228,26 @@ template <class T> function get_override(const T *this_ptr, const char *name) {
         );
       }
 \endrst */
+// clang-format on
 #define PYBIND11_OVERRIDE_NAME(ret_type, cname, name, fn, ...) \
     do { \
         PYBIND11_OVERRIDE_IMPL(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, __VA_ARGS__); \
         return cname::fn(__VA_ARGS__); \
     } while (false)
 
+// clang-format off
 /** \rst
     Macro for pure virtual functions, this function is identical to :c:macro:`PYBIND11_OVERRIDE_NAME`, except that it
     throws if no override can be found.
 \endrst */
+// clang-format on
 #define PYBIND11_OVERRIDE_PURE_NAME(ret_type, cname, name, fn, ...) \
     do { \
         PYBIND11_OVERRIDE_IMPL(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, __VA_ARGS__); \
         pybind11::pybind11_fail("Tried to call pure virtual function \"" PYBIND11_STRINGIFY(cname) "::" name "\""); \
     } while (false)
 
+// clang-format off
 /** \rst
     Macro to populate the virtual method in the trampoline class. This macro tries to look up the method
     from the Python side, deals with the :ref:`gil` and necessary argument conversions to call this method and return
@@ -2257,13 +2272,16 @@ template <class T> function get_override(const T *this_ptr, const char *name) {
           }
       };
 \endrst */
+// clang-format on
 #define PYBIND11_OVERRIDE(ret_type, cname, fn, ...) \
     PYBIND11_OVERRIDE_NAME(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), #fn, fn, __VA_ARGS__)
 
+// clang-format off
 /** \rst
     Macro for pure virtual functions, this function is identical to :c:macro:`PYBIND11_OVERRIDE`, except that it throws
     if no override can be found.
 \endrst */
+// clang-format on
 #define PYBIND11_OVERRIDE_PURE(ret_type, cname, fn, ...) \
     PYBIND11_OVERRIDE_PURE_NAME(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), #fn, fn, __VA_ARGS__)