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 }}
 
     - 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
-      uses: jwlawson/actions-setup-cmake@v1.3
+      uses: jwlawson/actions-setup-cmake@v1.4
 
     - name: Cache wheels
       if: runner.os == 'macOS'
@@ -173,9 +174,10 @@ jobs:
     # This makes two environment variables available in the following step(s)
     - name: Set Windows 🐍 2.7 environment variables
       if: matrix.python == 2.7 && runner.os == 'Windows'
+      shell: bash
       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
     # setuptools
@@ -362,7 +364,7 @@ jobs:
       run: python3 -m pip install --upgrade pip
 
     - name: Setup CMake 3.18
-      uses: jwlawson/actions-setup-cmake@v1.3
+      uses: jwlawson/actions-setup-cmake@v1.4
       with:
         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``,
     ``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
   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.
   `#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
   pybind11-bound enums should never be used for such conversion.
   `#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.
   `#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
   valid instance of that type, such as ``py::bytes(o)`` when ``py::object o``
   isn't a bytes instance.
   `#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.
   `#2334 <https://github.com/pybind/pybind11/pull/2334>`_
 
@@ -161,7 +161,7 @@ Smaller or developer focused features:
   requested ordering.
   `#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>`_
 
 * 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.
 
 
+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
 
     Added ``setup_helpers`` file.
@@ -271,11 +288,10 @@ standard explicitly with
 
 .. 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_EXTENSIONS OFF)  # optional, keep compiler extensionsn off
 
-
 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``
 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
 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
 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
 not changed since 2.5).
 
+.. _pybind11-mkdoc: https://github.com/pybind/pybind11-mkdoc
+
 CMake support:
 --------------
 
@@ -62,7 +63,7 @@ something. The changes are:
 
 * 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.
-  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.
 
 * 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
   pybind11 will cause pybind11 to use the new Python mechanisms instead of its
   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.