@@ -1,54 +1,54 @@
-# Python (beta)
+# Code intelligence for Python (beta)
 
 ![](https://user-images.githubusercontent.com/1387653/51012886-6a645400-1514-11e9-8958-8ebe3e40aff9.png)
 
-This extension adds Python code intelligence to Sourcegraph using a [Python language server](https://github.com/Microsoft/python-language-server) (the [@sourcegraph fork](https://github.com/sourcegraph/python-language-server/tree/wip2)).
+This extension provides Python code intelligence on Sourcegraph. Ensure this extension is enabled and then try it on some examples:
 
-[**🗃️ Source code**](https://github.com/sourcegraph/lang-python)
-
-[**➕ View in extension registry**](https://sourcegraph.com/extensions/sourcegraph/python)
-
-## Features
+-   Tensorflow: [tensorflow_ranking/examples/tf_ranking_libsvm.py](https://sourcegraph.com/github.com/tensorflow/ranking@931e4e18d68612d0b29dc3c81994acdd4b6ab743/-/blob/tensorflow_ranking/examples/tf_ranking_libsvm.py#L294:27&tab=references)
+-   Flask: [flask/views.py](https://sourcegraph.com/github.com/pallets/flask/-/blob/flask/views.py)
+-   Zulip: [corporate/lib/stripe.py](https://sourcegraph.com/github.com/zulip/zulip/-/blob/corporate/lib/stripe.py)
+-   Trivial sample: [pkg0/m0.py](http://sourcegraph.com/github.com/sgtest/python-sample-0/-/blob/pkg0/m0.py)
 
-For Python code viewed on [Sourcegraph](https://sourcegraph.com) and when using the [Sourcegraph browser extension](https://docs.sourcegraph.com/integration/browser_extension):
+![Screenshot](https://user-images.githubusercontent.com/1976/49628952-d4c92800-f99b-11e8-9605-d880b733cde6.png)
 
--   Hovers with documentation and inferred type signatures
--   Go to definition
--   Find references
+## Usage with private Sourcegraph instances
 
-## Usage on your own Sourcegraph instance
+This extension is configured to talk to a language server over WebSockets. If you are running a
+private Sourcegraph instance, you should run your own language server. The server is available as a
+Docker image `sourcegraph/lang-python` from Docker Hub.
 
-Run the language server Docker container:
+### Using Docker
 
-```
-docker run --rm -p 4288:4288 sourcegraph/lang-python:insiders
-```
+1. Run the Python language server Docker container:
 
-Add these to your Sourcegraph settings:
+    ```sh
+    docker run --rm -p 4288:4288 sourcegraph/lang-python:insiders
+    ```
 
-```
-  "python.languageServer.url": "ws://localhost:4288",
-  "python.sourcegraph.url": "http://host.docker.internal:7080",
-```
+1. Enable this extension on your Sourcegraph  https://sourcegraph.example.com/extensions/sourcegraph/lang-python
 
-If you're running on Linux, change `python.sourcegraph.url` to the IP given by:
 
-```bash
-ip addr show docker0 | grep -Po 'inet \K[\d.]+'
-```
+1. Add these to your Sourcegraph settings:
 
-## Usage on Sourcegraph.com
+    ```json
+      "python.languageServer.url": "ws://localhost:4288",
+      "python.sourcegraph.url": "http://host.docker.internal:7080",
+    ```
 
-This extension is enabled for all users by default on Sourcegraph.com and when using the [Sourcegraph browser extension](https://docs.sourcegraph.com/integration/browser_extension) on public code.
+    If you're running on Linux, change `python.sourcegraph.url` to the IP given by:
 
-To use it, just visit a Python file and hover over tokens. Examples:
+    ```bash
+    ip addr show docker0 | grep -Po 'inet \K[\d.]+'
+    ```
 
--   Tensorflow: [tensorflow_ranking/examples/tf_ranking_libsvm.py](https://sourcegraph.com/github.com/tensorflow/ranking@931e4e18d68612d0b29dc3c81994acdd4b6ab743/-/blob/tensorflow_ranking/examples/tf_ranking_libsvm.py#L294:27&tab=references)
--   Flask: [flask/views.py](https://sourcegraph.com/github.com/pallets/flask/-/blob/flask/views.py)
--   Zulip: [corporate/lib/stripe.py](https://sourcegraph.com/github.com/zulip/zulip/-/blob/corporate/lib/stripe.py)
--   Trivial sample: [pkg0/m0.py](http://sourcegraph.com/github.com/sgtest/python-sample-0/-/blob/pkg0/m0.py)
+### Authentication proxies and firewalls
 
-![Screenshot](https://user-images.githubusercontent.com/1976/49628952-d4c92800-f99b-11e8-9605-d880b733cde6.png)
+Some customers deploy Sourcegraph behind an authentication proxy or firewall. If you do this, we
+recommend deploying the language server behind the proxy so that it can issue requests directly to
+Sourcegraph without going through the proxy. (Otherwise, you will need to configure the language
+server to authenticate through your proxy.) Make sure you set `python.sourcegraphUrl` to the URL
+that the language server should use to reach Sourcegraph, which is likely different from the URL
+that end users use.
 
 ## Known issues