docs: minor cleanup (#2555)

* docs: minor cleanup

* ci: fix add-path command

* docs: add example of use in-place

* Update .github/workflows/ci.yml

.github/workflows/ci.yml

@@ -91,10 +91,11 @@ jobs:
         architecture: ${{ matrix.arch }}
         architecture: ${{ matrix.arch }}
 
 
     - name: Setup Boost (Windows / Linux latest)
     - name: Setup Boost (Windows / Linux latest)
-      run: echo "::set-env name=BOOST_ROOT::$BOOST_ROOT_1_72_0"
+      shell: bash
+      run: echo "BOOST_ROOT=$BOOST_ROOT_1_72_0" >> $GITHUB_ENV
 
 
     - name: Update CMake
     - name: Update CMake
-      uses: jwlawson/actions-setup-cmake@v1.3
+      uses: jwlawson/actions-setup-cmake@v1.4
 
 
     - name: Cache wheels
     - name: Cache wheels
       if: runner.os == 'macOS'
       if: runner.os == 'macOS'
@@ -173,9 +174,10 @@ jobs:
     # This makes two environment variables available in the following step(s)
     # This makes two environment variables available in the following step(s)
     - name: Set Windows 🐍 2.7 environment variables
     - name: Set Windows 🐍 2.7 environment variables
       if: matrix.python == 2.7 && runner.os == 'Windows'
       if: matrix.python == 2.7 && runner.os == 'Windows'
+      shell: bash
       run: |
       run: |
-        echo "::set-env name=DISTUTILS_USE_SDK::1"
-        echo "::set-env name=MSSdk::1"
+        echo "DISTUTILS_USE_SDK=1" >> $GITHUB_ENV
+        echo "MSSdk=1" >> $GITHUB_ENV
 
 
     # This makes sure the setup_helpers module can build packages using
     # This makes sure the setup_helpers module can build packages using
     # setuptools
     # setuptools
@@ -362,7 +364,7 @@ jobs:
       run: python3 -m pip install --upgrade pip
       run: python3 -m pip install --upgrade pip
 
 
     - name: Setup CMake 3.18
     - name: Setup CMake 3.18
-      uses: jwlawson/actions-setup-cmake@v1.3
+      uses: jwlawson/actions-setup-cmake@v1.4
       with:
       with:
         cmake-version: 3.18
         cmake-version: 3.18
 
 

docs/changelog.rst

@@ -91,12 +91,12 @@ See :ref:`upgrade-guide-2.6` for help upgrading to the new version.
   * Helper functions ``pybind11_strip``, ``pybind11_extension``,
   * Helper functions ``pybind11_strip``, ``pybind11_extension``,
     ``pybind11_find_import`` added, see :doc:`cmake/index`.
     ``pybind11_find_import`` added, see :doc:`cmake/index`.
 
 
-* Optional :ref:`find-python-mode` and :ref:`nopython-mode` with CMake.
-  `#2370 <https://github.com/pybind/pybind11/pull/2370>`_
+  * Optional :ref:`find-python-mode` and :ref:`nopython-mode` with CMake.
+    `#2370 <https://github.com/pybind/pybind11/pull/2370>`_
 
 
-* Uninstall target added.
-  `#2265 <https://github.com/pybind/pybind11/pull/2265>`_ and
-  `#2346 <https://github.com/pybind/pybind11/pull/2346>`_
+  * Uninstall target added.
+    `#2265 <https://github.com/pybind/pybind11/pull/2265>`_ and
+    `#2346 <https://github.com/pybind/pybind11/pull/2346>`_
 
 
 * ``PYBIND11_OVERLOAD*`` macros and ``get_overload`` function replaced by
 * ``PYBIND11_OVERLOAD*`` macros and ``get_overload`` function replaced by
   correctly-named ``PYBIND11_OVERRIDE*`` and ``get_override``, fixing
   correctly-named ``PYBIND11_OVERRIDE*`` and ``get_override``, fixing
@@ -107,7 +107,7 @@ See :ref:`upgrade-guide-2.6` for help upgrading to the new version.
 * Error now thrown when ``__init__`` is forgotten on subclasses.
 * Error now thrown when ``__init__`` is forgotten on subclasses.
   `#2152 <https://github.com/pybind/pybind11/pull/2152>`_
   `#2152 <https://github.com/pybind/pybind11/pull/2152>`_
 
 
-* `py::class_<union_type>` is now supported. Note that writing to one data
+* ``py::class_<union_type>`` is now supported. Note that writing to one data
   member of the union and reading another (type punning) is UB in C++. Thus
   member of the union and reading another (type punning) is UB in C++. Thus
   pybind11-bound enums should never be used for such conversion.
   pybind11-bound enums should never be used for such conversion.
   `#2320 <https://github.com/pybind/pybind11/pull/2320>`_.
   `#2320 <https://github.com/pybind/pybind11/pull/2320>`_.
@@ -123,14 +123,14 @@ Smaller or developer focused features:
 * ``py::ellipsis`` now also works on Python 2.
 * ``py::ellipsis`` now also works on Python 2.
   `#2360 <https://github.com/pybind/pybind11/pull/2360>`_
   `#2360 <https://github.com/pybind/pybind11/pull/2360>`_
 
 
-* Throw if conversion to ``str`` fails.
-  `#2477 <https://github.com/pybind/pybind11/pull/2477>`_
-
 * Throw error if conversion to a pybind11 type if the Python object isn't a
 * Throw error if conversion to a pybind11 type if the Python object isn't a
   valid instance of that type, such as ``py::bytes(o)`` when ``py::object o``
   valid instance of that type, such as ``py::bytes(o)`` when ``py::object o``
   isn't a bytes instance.
   isn't a bytes instance.
   `#2349 <https://github.com/pybind/pybind11/pull/2349>`_
   `#2349 <https://github.com/pybind/pybind11/pull/2349>`_
 
 
+* Throw if conversion to ``str`` fails.
+  `#2477 <https://github.com/pybind/pybind11/pull/2477>`_
+
 * Pointer to ``std::tuple`` & ``std::pair`` supported in cast.
 * Pointer to ``std::tuple`` & ``std::pair`` supported in cast.
   `#2334 <https://github.com/pybind/pybind11/pull/2334>`_
   `#2334 <https://github.com/pybind/pybind11/pull/2334>`_
 
 
@@ -161,7 +161,7 @@ Smaller or developer focused features:
   requested ordering.
   requested ordering.
   `#2484 <https://github.com/pybind/pybind11/pull/2484>`_
   `#2484 <https://github.com/pybind/pybind11/pull/2484>`_
 
 
-* PyPy fixes, including support for PyPy3 and PyPy 7.
+* PyPy fixes, PyPy 7.3.x now supported, including PyPy3.
   `#2146 <https://github.com/pybind/pybind11/pull/2146>`_
   `#2146 <https://github.com/pybind/pybind11/pull/2146>`_
 
 
 * CPython 3.9 fixes.
 * CPython 3.9 fixes.

docs/compiling.rst

@@ -157,6 +157,23 @@ this, you will need to import from a local file in ``setup.py`` and ensure the
 helper file is part of your MANIFEST.
 helper file is part of your MANIFEST.
 
 
 
 
+Closely related, if you include pybind11 as a subproject, you can run the
+``setup_helpers.py`` inplace. If loaded correctly, this should even pick up
+the correct include for pybind11, though you can turn it off as shown above if
+you want to input it manually.
+
+Suggested usage if you have pybind11 as a submodule in ``extern/pybind11``:
+
+.. code-block:: python
+
+    DIR = os.path.abspath(os.path.dirname(__file__))
+
+    sys.path.append(os.path.join(DIR, "extern", "pybind11"))
+    from pybind11.setup_helpers import Pybind11Extension  # noqa: E402
+
+    del sys.path[-1]
+
+
 .. versionchanged:: 2.6
 .. versionchanged:: 2.6
 
 
     Added ``setup_helpers`` file.
     Added ``setup_helpers`` file.
@@ -271,11 +288,10 @@ standard explicitly with
 
 
 .. code-block:: cmake
 .. code-block:: cmake
 
 
-    set(CMAKE_CXX_STANDARD 14)  # or 11, 14, 17, 20
+    set(CMAKE_CXX_STANDARD 14 CACHE STRING "C++ version selection")  # or 11, 14, 17, 20
     set(CMAKE_CXX_STANDARD_REQUIRED ON)  # optional, ensure standard is supported
     set(CMAKE_CXX_STANDARD_REQUIRED ON)  # optional, ensure standard is supported
     set(CMAKE_CXX_EXTENSIONS OFF)  # optional, keep compiler extensionsn off
     set(CMAKE_CXX_EXTENSIONS OFF)  # optional, keep compiler extensionsn off
 
 
-
 The variables can also be set when calling CMake from the command line using
 The variables can also be set when calling CMake from the command line using
 the ``-D<variable>=<value>`` flag. You can also manually set ``CXX_STANDARD``
 the ``-D<variable>=<value>`` flag. You can also manually set ``CXX_STANDARD``
 on a target or use ``target_compile_features`` on your targets - anything that
 on a target or use ``target_compile_features`` on your targets - anything that

docs/upgrade.rst

@@ -17,7 +17,6 @@ The ``tools/clang`` submodule and ``tools/mkdoc.py`` have been moved to a
 standalone package, `pybind11-mkdoc`_. If you were using those tools, please
 standalone package, `pybind11-mkdoc`_. If you were using those tools, please
 use them via a pip install from the new location.
 use them via a pip install from the new location.
 
 
-.. _pybind11-mkdoc: https://github.com/pybind/pybind11-mkdoc
 
 
 An error is now thrown when ``__init__`` is forgotten on subclasses. This was
 An error is now thrown when ``__init__`` is forgotten on subclasses. This was
 incorrect before, but was not checked. Add a call to ``__init__`` if it is
 incorrect before, but was not checked. Add a call to ``__init__`` if it is
@@ -49,6 +48,8 @@ be unaffected, as the ``pybind11/include`` location is reported by ``python -m
 pybind11 --includes`` and ``pybind11.get_include()`` is still correct and has
 pybind11 --includes`` and ``pybind11.get_include()`` is still correct and has
 not changed since 2.5).
 not changed since 2.5).
 
 
+.. _pybind11-mkdoc: https://github.com/pybind/pybind11-mkdoc
+
 CMake support:
 CMake support:
 --------------
 --------------
 
 
@@ -62,7 +63,7 @@ something. The changes are:
 
 
 * If you do not request a standard, pybind11 targets will compile with the
 * If you do not request a standard, pybind11 targets will compile with the
   compiler default, but not less than C++11, instead of forcing C++14 always.
   compiler default, but not less than C++11, instead of forcing C++14 always.
-  If you depend on the old behavior, please use ``set(CMAKE_CXX_STANDARD 14)``
+  If you depend on the old behavior, please use ``set(CMAKE_CXX_STANDARD 14 CACHE STRING "")``
   instead.
   instead.
 
 
 * Direct ``pybind11::module`` usage should always be accompanied by at least
 * Direct ``pybind11::module`` usage should always be accompanied by at least
@@ -88,7 +89,8 @@ In addition, the following changes may be of interest:
 * Using ``find_package(Python COMPONENTS Interpreter Development)`` before
 * Using ``find_package(Python COMPONENTS Interpreter Development)`` before
   pybind11 will cause pybind11 to use the new Python mechanisms instead of its
   pybind11 will cause pybind11 to use the new Python mechanisms instead of its
   own custom search, based on a patched version of classic ``FindPythonInterp``
   own custom search, based on a patched version of classic ``FindPythonInterp``
-  / ``FindPythonLibs``. In the future, this may become the default.
+  / ``FindPythonLibs``. In the future, this may become the default. A recent
+  (3.15+ or 3.18.2+) version of CMake recommended.