Add upgrade guide to the documentation

[skip ci]

docs/changelog.rst

@@ -60,7 +60,8 @@ v2.2.0 (Not yet released)
 
 
 * pybind11's headers and build system now more strictly enforce hidden symbol
 * pybind11's headers and build system now more strictly enforce hidden symbol
   visibility for extension modules. This should be seamless for most users,
   visibility for extension modules. This should be seamless for most users,
-  but see the upgrade guide if you use a custom build system.
+  but see the :doc:`upgrade` if you use a custom build system.
+  `#995 <https://github.com/pybind/pybind11/pull/995>`_.
 
 
 * Support for ``py::module_local`` types which allow multiple modules to
 * Support for ``py::module_local`` types which allow multiple modules to
   export the same C++ types without conflicts. This is useful for opaque
   export the same C++ types without conflicts. This is useful for opaque

docs/index.rst

@@ -14,6 +14,7 @@ pybind11 --- Seamless operability between C++11 and Python
 
 
    intro
    intro
    changelog
    changelog
+   upgrade
 
 
 .. toctree::
 .. toctree::
    :caption: The Basics
    :caption: The Basics