Expanding documentaiton for different configuration scenarios

- Adding link to docs in sourcegraph config UI
- Update docs to include opt-in flow

app/views/admin/application_settings/_sourcegraph.html.haml

@@ -8,7 +8,7 @@
     %button.btn.btn-default.js-settings-toggle{ type: 'button' }
       = expanded ? _('Collapse') : _('Expand')
     %p
-      = _('Enable code intelligence powered by %{link}.').html_safe % { link: link_to('Sourcegraph', 'https://sourcegraph.com', target: '_blank') }
+      = _('Enable code intelligence powered by %{link} on your GitLab instance\'s code views and merge requests.').html_safe % { link: link_to('Sourcegraph', 'https://sourcegraph.com/', target: '_blank') }
 
   .settings-content
     = form_for @application_setting, url: integrations_admin_application_settings_path(anchor: 'js-sourcegraph-settings'), html: { class: 'fieldset-form' } do |f|
@@ -19,6 +19,9 @@
           .form-check
             = f.check_box :sourcegraph_enabled, class: 'form-check-input'
             = f.label :sourcegraph_enabled, _('Enable Sourcegraph'), class: 'form-check-label'
+            = link_to icon('question-circle'),
+              help_page_path('integration/sourcegraph.md'),
+              target: '_blank'
         .form-group
           = f.label :sourcegraph_url, _('Sourcegraph URL'), class: 'label-bold'
           = f.text_field :sourcegraph_url, class: 'form-control', placeholder: 'e.g. https://sourcegraph.example.com'

doc/integration/sourcegraph.md

@@ -6,15 +6,39 @@ type: reference, how-to
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/16556) in GitLab X.X.
 
-[Sourcegraph](https://sourcegraph.com) provides complete code intelligence functionality
-(historically provided by the Sourcegraph browser extension) including hover tooltips and go-to-definition
-working by default for all users.
+[Sourcegraph](https://sourcegraph.com) provides complete code intelligence functionality,
+historically provided by the Sourcegraph browser extension. Sourcegraph provides tooltips on hover with go-to definitions as well as
+find references working by default for all users.
 
-## Setup **(CORE ONLY)**
+## Set up for public repositories on GitLab.com
+
+With an opt-in setting, this works by default for all public repositories on GitLab.com.
+
+1. In GitLab, click your avatar in the top-right corner, then **Settings**. On the left-hand nav, click **Preferences**.
+1. Under **Integrations**, find the **Sourcegraph** section.
+1. Check **Enable Sourcegraph**.
+
+## Set up for private repositories on GitLab.com
+
+Since [Sourcegraph.com](http://sourcegraph.com/search) does not access private repositories on GitLab.com, you will need to run a private instance of Sourcegraph to generate code intelligence.
+
+### Set up and configure your Sourcegraph instance
+
+Follow the [setup](#set-up-your-sourcegraph-instance) and [configure](#configure-your-sourcegraph-instance-with-gitlab) steps in the self-managed instance section below.
+
+### Install the Sourcegraph browser extension
+
+To share code intelligence information from your private Sourcegraph instance, you will need to use the Sourcegraph browser extension to reach back to your private Sourcegraph instance from private GitLab repository pages.
+
+1. [Install the Sourcegraph browser extension](https://docs.sourcegraph.com/integration/browser_extension).
+1. Right-click the browser extension icon and set the Sourcegraph URL field to your Sourcegraph instance's URL.
+1. [Enable the browser extension](https://docs.sourcegraph.com/integration/browser_extension#enabling-the-browser-extension-on-your-code-host) on GitLab.com.
+
+You should now see code intelligence on any repository indexed by your private Sourcegraph instance.
+
+## Set up for self-managed GitLab instances **(CORE ONLY)**
 
-> These steps are required for self-managed instances.
 > Once enabled in your instance, it will become available to all projects (public, internal, and private).
-> Sourcegraph integration is already enabled on GitLab.com and ready to use but restricted to only **public** projects.
 
 Before you can enable Sourcegraph code intelligence in GitLab you need to have a
 Sourcegraph instance running and configured with your GitLab instance as an external
@@ -24,7 +48,7 @@ service.
 
 If you are new to Sourcegraph, head over to the [Sourcegraph installation documentation](https://docs.sourcegraph.com/admin) and get your instance up and running.
 
-### Configure your Sourcegraph instance with GitLab
+### Connect your Sourcegraph instance to GitLab
 
 1. Navigate to the site admin area in Sourcegraph.
 1. [Configure your GitLab external service](https://docs.sourcegraph.com/admin/external_service/gitlab).
@@ -36,7 +60,7 @@ You can skip this step if you already have your GitLab repositories searchable i
 
 1. In GitLab, go to **Admin Area > Settings > Integrations**.
 1. Expand the **Sourcegraph** configuration section.
-1. Check the **Enable Sourcegraph** checkbox.
+1. Check **Enable Sourcegraph**.
 1. Set the Sourcegraph URL to your Sourcegraph instance, e.g., `https://sourcegraph.example.com`.
 
 You should now see code intelligence on your files, without needing the browser

locale/gitlab.pot

@@ -887,9 +887,6 @@ msgid_plural "Add %d issues"
 msgstr[0] ""
 msgstr[1] ""
 
-msgid "Add %{link} code intelligence to your GitLab instance code views and pull requests."
-msgstr ""
-
 msgid "Add CHANGELOG"
 msgstr ""
 
@@ -6259,7 +6256,7 @@ msgstr ""
 msgid "Enable classification control using an external service"
 msgstr ""
 
-msgid "Enable code intelligence powered by %{link}."
+msgid "Enable code intelligence powered by %{link} on your GitLab instance's code views and merge requests."
 msgstr ""
 
 msgid "Enable error tracking"