docs: installing section (#2494)

* docs: installing section

* docs: feedback from @wjakob

docs/compiling.rst

@@ -523,23 +523,11 @@ build system that works on all platforms including Windows.
     contains one (which will lead to a segfault).
 
 
-Building with vcpkg
+Building with Bazel
 ===================
-You can download and install pybind11 using the Microsoft `vcpkg
-<https://github.com/Microsoft/vcpkg/>`_ dependency manager:
 
-.. code-block:: bash
+You can build with the Bazel build system using the `pybind11_bazel
-
+<https://github.com/pybind/pybind11_bazel>`_ repository.
-    git clone https://github.com/Microsoft/vcpkg.git
-    cd vcpkg
-    ./bootstrap-vcpkg.sh
-    ./vcpkg integrate install
-    vcpkg install pybind11
-
-The pybind11 port in vcpkg is kept up to date by Microsoft team members and
-community contributors. If the version is out of date, please `create an issue
-or pull request <https://github.com/Microsoft/vcpkg/>`_ on the vcpkg
-repository.
 
 Generating binding code automatically
 =====================================

docs/index.rst

@@ -5,6 +5,8 @@
 pybind11 --- Seamless operability between C++11 and Python
 ==========================================================
 
+Source code available at `github.com/pybind/pybind11 <https://github.com/pybind/pybind11>`_.
+
 .. only: not latex
 
     Contents:
@@ -20,6 +22,7 @@ pybind11 --- Seamless operability between C++11 and Python
    :caption: The Basics
    :maxdepth: 2
 
+   installing
    basics
    classes
    compiling

docs/installing.rst

@@ -0,0 +1,103 @@
+.. _installing:
+
+Installing the library
+######################
+
+There are several ways to get the pybind11 source, which lives at
+`pybind/pybind11 on GitHub <https://github.com/pybind/pybind11>`_. The pybind11
+developers recommend one of the first three ways listed here, submodule, PyPI,
+or conda-forge, for obtaining pybind11.
+
+Include as a submodule
+======================
+
+When you are working on a project in Git, you can use the pybind11 repository
+as a submodule. From your git repository, use:
+
+.. code-block:: bash
+
+    git submodule add ../../pybind/pybind11 extern/pybind11 -b stable
+    git submodule update --init
+
+This assumes you are placing your dependencies in ``extern/``, and that you are
+using GitHub; if you are not using GitHub, use the full https or ssh URL
+instead of the relative URL ``../../pybind/pybind11`` above. Some other servers
+also require the ``.git`` extension (GitHub does not).
+
+From here, you can now include ``extern/pybind11/include``, or you can use
+the various integration tools (see :ref:`compiling`) pybind11 provides directly
+from the local folder.
+
+Include with PyPI
+=================
+
+You can download the sources and CMake files as a Python package from PyPI
+using Pip. Just use:
+
+.. code-block:: bash
+
+    pip install pybind11
+
+This will provide pybind11 in a standard Python package format. If you want
+pybind11 available directly in your environment root, you can use:
+
+.. code-block:: bash
+
+    pip install "pybind11[global]"
+
+This is not recommended if you are installing with your system Python, as it
+will add files to ``/usr/local/include/pybind11`` and
+``/usr/local/share/cmake/pybind11``, so unless that is what you want, it is
+recommended only for use in virtual environments or your ``pyproject.toml``
+file (see :ref:`compiling`).
+
+Include with conda-forge
+========================
+
+You can use pybind11 with conda packaging via `conda-forge
+<https://github.com/conda-forge/pybind11-feedstock>`_:
+
+.. code-block:: bash
+
+    conda install -c conda-forge pybind11
+
+
+Include with vcpkg
+==================
+You can download and install pybind11 using the Microsoft `vcpkg
+<https://github.com/Microsoft/vcpkg/>`_ dependency manager:
+
+.. code-block:: bash
+
+    git clone https://github.com/Microsoft/vcpkg.git
+    cd vcpkg
+    ./bootstrap-vcpkg.sh
+    ./vcpkg integrate install
+    vcpkg install pybind11
+
+The pybind11 port in vcpkg is kept up to date by Microsoft team members and
+community contributors. If the version is out of date, please `create an issue
+or pull request <https://github.com/Microsoft/vcpkg/>`_ on the vcpkg
+repository.
+
+Global install with brew
+========================
+
+The brew package manager (Homebrew on macOS, or Linuxbrew on Linux) has a
+`pybind11 package
+<https://github.com/Homebrew/homebrew-core/blob/master/Formula/pybind11.rb>`_.
+To install:
+
+.. code-block:: bash
+
+    brew install pybind11
+
+.. We should list Conan, and possibly a few other C++ package managers (hunter,
+.. perhaps). Conan has a very clean CMake integration that would be good to show.
+
+Other options
+=============
+
+Other locations you can find pybind11 are `listed here
+<https://repology.org/project/python:pybind11/versions>`_; these are maintained
+by various packagers and the community.