style: add clang-format file (#2310)
* style: adding clang-format as manual hook
* docs: adding a Clang-Format section. (#2803)
Co-authored-by: Ralf W. Grosse-Kunstleve <rwgk@google.com>
diff --git a/.clang-format b/.clang-format
new file mode 100644
index 0000000..8700fca
--- /dev/null
+++ b/.clang-format
@@ -0,0 +1,21 @@
+---
+# See all possible options and defaults with:
+# clang-format --style=llvm --dump-config
+BasedOnStyle: LLVM
+AccessModifierOffset: -4
+AlignConsecutiveAssignments: true
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBinaryOperators: All
+BreakConstructorInitializers: BeforeColon
+ColumnLimit: 99
+IndentCaseLabels: true
+IndentPPDirectives: AfterHash
+IndentWidth: 4
+Language: Cpp
+SpaceAfterCStyleCast: true
+# SpaceInEmptyBlock: true # too new
+Standard: Cpp11
+TabWidth: 4
+...
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index d9c91bd..08d9e7c 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -176,10 +176,35 @@
pre-commit install
```
+### Clang-Format
+
+As of v2.6.2, pybind11 ships with a [`clang-format`][clang-format]
+configuration file at the top level of the repo (the filename is
+`.clang-format`). Currently, formatting is NOT applied automatically, but
+manually using `clang-format` for newly developed files is highly encouraged.
+To check if a file needs formatting:
+
+```bash
+clang-format -style=file --dry-run some.cpp
+```
+
+The output will show things to be fixed, if any. To actually format the file:
+
+```bash
+clang-format -style=file -i some.cpp
+```
+
+Note that the `-style-file` option searches the parent directories for the
+`.clang-format` file, i.e. the commands above can be run in any subdirectory
+of the pybind11 repo.
+
### Clang-Tidy
-To run Clang tidy, the following recipe should work. Files will be modified in
-place, so you can use git to monitor the changes.
+[`clang-tidy`][clang-tidy] performs deeper static code analyses and is
+more complex to run, compared to `clang-format`, but support for `clang-tidy`
+is built into the pybind11 CMake configuration. To run `clang-tidy`, the
+following recipe should work. Files will be modified in place, so you can
+use git to monitor the changes.
```bash
docker run --rm -v $PWD:/pybind11 -it silkeh/clang:10
@@ -198,7 +223,7 @@
cmake --build build
```
-The report is sent to stderr; you can pip it into a file if you wish.
+The report is sent to stderr; you can pipe it into a file if you wish.
### Build recipes
@@ -325,6 +350,8 @@
[pre-commit]: https://pre-commit.com
+[clang-format]: https://clang.llvm.org/docs/ClangFormat.html
+[clang-tidy]: https://clang.llvm.org/extra/clang-tidy/
[pybind11.readthedocs.org]: http://pybind11.readthedocs.org/en/latest
[issue tracker]: https://github.com/pybind/pybind11/issues
[gitter]: https://gitter.im/pybind/Lobby
diff --git a/include/pybind11/iostream.h b/include/pybind11/iostream.h
index 816e38f..59d33e9 100644
--- a/include/pybind11/iostream.h
+++ b/include/pybind11/iostream.h
@@ -104,8 +104,10 @@
.. code-block:: cpp
{
- py::scoped_ostream_redirect output{std::cerr, py::module_::import("sys").attr("stderr")};
- std::cerr << "Hello, World!";
+ py::scoped_ostream_redirect output{
+ std::cerr,
+ py::module::import("sys").attr("stderr")
+ };
}
\endrst */
class scoped_ostream_redirect {
diff --git a/setup.cfg b/setup.cfg
index e7fc8f4..80a361d 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -43,12 +43,7 @@
docs/**
tools/**
include/**
- .appveyor.yml
- .cmake-format.yaml
- .gitmodules
- .pre-commit-config.yaml
- .readthedocs.yml
- .clang-tidy
+ .*
pybind11/include/**
pybind11/share/**
CMakeLists.txt
