From b7faa3896049ec2d9cf82e748dd827be18d07d5b Mon Sep 17 00:00:00 2001
From: Ines Montani <ines@ines.io>
Date: Tue, 15 Sep 2020 12:44:03 +0200
Subject: [PATCH] Update docs [ci skip]

---
 website/docs/usage/index.md | 55 +++++++++++++++++++++++++++----------
 website/docs/usage/v3.md    |  5 ++++
 2 files changed, 45 insertions(+), 15 deletions(-)

diff --git a/website/docs/usage/index.md b/website/docs/usage/index.md
index 170e16591..ad2614175 100644
--- a/website/docs/usage/index.md
+++ b/website/docs/usage/index.md
@@ -170,27 +170,52 @@ Compared to regular install via pip, the
 developer dependencies such as Cython. See the [quickstart widget](#quickstart)
 to get the right commands for your platform and Python version.
 
-#### Ubuntu {#source-ubuntu}
+<a id="source-ubuntu"></a><a id="source-osx"></a><a id="source-windows"></a>
 
-Install system-level dependencies via `apt-get`:
+- **Ubuntu:** Install system-level dependencies via `apt-get`:
+  `sudo apt-get install build-essential python-dev git`
+- **macOS / OS X:** Install a recent version of
+  [XCode](https://developer.apple.com/xcode/), including the so-called "Command
+  Line Tools". macOS and OS X ship with Python and git preinstalled.
+- **Windows:** Install a version of the
+  [Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
+  or
+  [Visual Studio Express](https://www.visualstudio.com/vs/visual-studio-express/)
+  that matches the version that was used to compile your Python interpreter.
+
+### Building an executable {#executable}
+
+The spaCy repository includes a [`Makefile`](%%GITHUB_SPACY/Makefile) that
+builds an executable zip file using [`pex`](https://github.com/pantsbuild/pex)
+(**P**ython **Ex**ecutable). The executable includes spaCy and all its package
+dependencies and only requires the system Python at runtime. Building an
+executable `.pex` file is often the most convenient way to deploy spaCy, as it
+lets you separate the build from the deployment process.
+
+> #### Usage
+>
+> To use a `.pex` file, just replace `python` with the path to the file when you
+> execute your code or CLI commands. This is equivalent to running Python in a
+> virtual environment with spaCy installed.
+>
+> ```bash
+> $ ./spacy.pex my_script.py
+> $ ./spacy.pex -m spacy info
+> ```
 
 ```bash
-$ sudo apt-get install build-essential python-dev git
+$ git clone https://github.com/explosion/spaCy
+$ cd spaCy
+$ make
 ```
 
-#### macOS / OS X {#source-osx}
+You can configure the build process with the following environment variables:
 
-Install a recent version of [XCode](https://developer.apple.com/xcode/),
-including the so-called "Command Line Tools". macOS and OS X ship with Python
-and git preinstalled.
-
-#### Windows {#source-windows}
-
-Install a version of the
-[Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
-or
-[Visual Studio Express](https://www.visualstudio.com/vs/visual-studio-express/)
-that matches the version that was used to compile your Python interpreter.
+| Variable       | Description                                                                                                                                                                                                 |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SPACY_EXTRAS` | Additional Python packages to install alongside spaCy with optional version specifications. Should be a string that can be passed to `pip install`. See [`Makefile`](%%GITHUB_SPACY/Makefile) for defaults. |
+| `PYVER`        | The Python version to build against. This version needs to be available on your build and runtime machines. Defaults to `3.6`.                                                                              |
+| `WHEELHOUSE`   | Directory to store the wheel files during compilation. Defaults to `./wheelhouse`.                                                                                                                          |
 
 ### Run tests {#run-tests}
 
diff --git a/website/docs/usage/v3.md b/website/docs/usage/v3.md
index 4d30477e1..44810da58 100644
--- a/website/docs/usage/v3.md
+++ b/website/docs/usage/v3.md
@@ -346,6 +346,8 @@ A pattern added to the dependency matcher consists of a **list of
 dictionaries**, with each dictionary describing a **token to match** and its
 **relation to an existing token** in the pattern.
 
+![Dependency matcher pattern](../images/dep-match-diagram.svg)
+
 <Infobox title="Details & Documentation" emoji="📖" list>
 
 - **Usage:**
@@ -538,6 +540,9 @@ Note that spaCy v3.0 now requires **Python 3.6+**.
   doesn't provide lemmas by default or switch automatically between lookup and
   rule-based lemmas. You can now add it to your pipeline explicitly and set its
   mode on initialization.
+- Various keyword arguments across functions and methods are now explicitly
+  declared as _keyword-only_ arguments. Those arguments are documented
+  accordingly across the API reference.
 
 ### Removed or renamed API {#incompat-removed}