Docs working branch for Sourcegraph November release (#805)

This is the docs working branch for SG Nov 25th release. It has release
docs for:

- Sunsetting commands and custom commands
- New docs for prompts and prompts library
- Admin pre-instructions for Cody
- Enterprise model configuration

---------

Co-authored-by: Zahid Ali <[email protected]>
Co-authored-by: Taras Yemets <[email protected]>
Co-authored-by: Emi (stephen) Gutekanst <[email protected]>
Co-authored-by: Aravind Ramaraju <[email protected]>
Co-authored-by: David Veszelovszki <[email protected]>

Author: 6 people

README.md

@@ -1,6 +1,6 @@
 # Sourcegraph Docs
 
-<!-- Working branch for October 30th 2024 Release -->
+<!-- Working branch for Nov 25th 2024 Release -->
 
 Welcome to the Sourcegraph documentation! We're excited to have you contribute to our docs. We've recently rearchitectured our docs tech stack — powered by Next.js, TailwindCSS and deployed on Vercel. This guide will walk you through the process of contributing to our documentation using the new tech stack.
 
@@ -148,7 +148,7 @@ As you make changes to the documentation, the development server will automatica
 
 ### Previewing Vercel Deployments
 
-When you open a PR Vercel deploys and provides you with a preview deployment link. To view your deployment, click the "Visit Preview" and then append `/docs` at the end of the URL. The original link gives you a `404`. 
+When you open a PR Vercel deploys and provides you with a preview deployment link. To view your deployment, click the "Visit Preview" and then append `/docs` at the end of the URL. The original link gives you a `404`.
 
 ![CleanShot 2024-11-05 at 10 11 29@2x](https://github.com/user-attachments/assets/b0911e2e-95a7-4f56-b2ff-b659d13077d8)
 

docs.config.js

@@ -1,5 +1,5 @@
 const config = {
-	DOCS_LATEST_VERSION: '5.9'
+	DOCS_LATEST_VERSION: '5.10'
 };
 
 module.exports = config;

docs/cody/capabilities/chat.mdx

@@ -86,21 +86,9 @@ Smart Apply also supports the executing of commands in the terminal. When you as
 
 Cody keeps a history of your chat sessions. You can view it by clicking the **History** button in the chat panel. You can **Export** it to a JSON file for later use or click the **Delete all** button to clear the chat history.
 
-## Prompts and Commands
+## Prompts
 
-Cody offers quick, ready-to-use [prompts and commands](/cody/capabilities/commands) for common actions to write, describe, fix, and smell code. These allow you to run predefined actions with smart context-fetching anywhere in the editor, like:
-
-- **New Chat**: Ask Cody a question
-- **Document Code**: Add code documentation
-- **Edit Code**: Edit code with instructions
-- **Explain Code**: Describe your code with more details
-- **Generate Unit Tests**: Write tests for your code
-
-<video width="1920" height="1080" loop playsInline controls style={{ width: '100%', height: 'auto' }}>
-  <source src="https://storage.googleapis.com/sourcegraph-assets/Docs/Media/cody-prompts-102024-2.mp4" type="video/mp4" />
-  </video>
-
-Read more about [prompts and commands](/cody/capabilities/commands).
+Cody offers quick, ready-to-use [prompts](/cody/capabilities/commands) for common actions to write, describe, fix, and smell code. Read more about [prompts](/cody/capabilities/commands) here.
 
 ## Ask Cody to write code
 

docs/cody/capabilities/commands.mdx

@@ -23,17 +23,13 @@ sum(3 , 4);
 
 When you try to `console.log` the `result`, it does not print the correct summed value. Cody can help you both identify the error and provide a solution to fix it. Let's debug the code snippet. Paste the code snippet inside the Cody chat window and ask Cody to fix it.
 
-<video width="1920" height="1080" loop playsInline controls style={{ width: '100%', height: 'auto' }}>
-	<source src="https://storage.googleapis.com/sourcegraph-assets/Docs/Media/fix-code.mp4" type="video/mp4" />
-</video>
-
 In addition, Cody helps you reduce the chances of getting syntax and typo errors. The Cody IDE extensions provide context-aware suggestions based on your codebase, helping you avoid common mistakes and reduce debugging time.
 
 ## Detecting code smell
 
 Cody can detect early code smells to ensure coding best practices and quality and provide suggestions to improve your code. By detecting such potential errors early on, you can avoid scalability and code maintainability issues that might arise in the future.
 
-You can detect code smells by the **Find Code Smells** command from the Prompts drop-down menu in the chat panel.
+You can detect code smells by the **find-code-smells** prompt from the Prompts drop-down menu in the chat panel. If you want to refine your debugging process, you can create a new prompt from the Prompt Library and use it to debug your code.
 
 ## Code Actions
 

docs/cody/capabilities/debug-code.mdx

@@ -92,8 +92,6 @@ The `exclude` field can also include a catch-all condition, such as a `regexp` t
 
 Some Cody features, such as using **Prompts**, will not work if the `exclude` rules are defined. They appear to be disabled in the Cody chat interface. If you try running any of these, you'll be prompted with an error message. However, Cody chat will still work; you can use it to ask questions.
 
-![commands-disabled-exclude-rules](https://storage.googleapis.com/sourcegraph-assets/Docs/commands-disabled-082024.png)
-
 ### Both `include` and `exclude` rules are specified
 
 When requesting third-party LLMs, Cody can use content from a repository if its name matches any of the `include` patterns and does not match any of the `exclude` patterns. Thus, the `exclude` rules filter only the repositories allowed by the `include` rules. For example,

docs/cody/capabilities/ignore-context.mdx

@@ -10,7 +10,7 @@
 
 <QuickLink title="Autocomplete" icon='installation' href="/cody/capabilities/autocomplete" description="Suggests code completions as you type, utilizing context from your code, open files, and file history." />
 
-<QuickLink title="Prompts & Commands" icon='theming' href="/cody/capabilities/commands" description="Automate key tasks in your workflow with premade and customizable prompts." />
+<QuickLink title="Prompts & Prompt Library" icon='theming' href="/cody/capabilities/commands" description="Automate key tasks in your workflow with premade and customizable prompts." />
 
 <QuickLink title="OpenCtx Context Providers" icon='presets' href="/cody/capabilities/openctx" description="Add additional context sources from outside of your code base by leveraging OpenCtx Providers." />
 

docs/cody/capabilities/index.mdx

@@ -55,3 +55,9 @@ If Cody's answer isn't helpful, you can try asking again with a different contex
 ![re-run-prompts](https://storage.googleapis.com/sourcegraph-assets/Docs/rerun-prompt-web-0724.jpg)
 
 <Callout type="tip">For a detailed breakdown of Cody's capabilities across different clients [read these feature parity docs](/cody/clients/feature-reference).</Callout>
+
+## Prompts
+
+Cody allows you create quick, ready-to-use [prompts](/cody/capabilities/commands) to automate key tasks in your workflow. Prompts are created and saved in the Prompt Library and can be accessed from the **Tools > Prompt Library** in the top navigation bar in your Sourcegraph instance.
+
+![cody-web-prompts](https://storage.googleapis.com/sourcegraph-assets/Docs/cody-web-prompts-1124.png)

docs/cody/clients/cody-with-sourcegraph.mdx

@@ -1,101 +1,117 @@
-# Cody on Sourcegraph Enterprise
+# Cody for Enterprise
 
 <p className="subtitle">Cody enhances your coding experience by providing intelligent code suggestions, context-aware completions, and advanced code analysis. These docs will help you use Cody on your Sourcegraph Enterprise instance.</p>
 
 <LinkCards>
    <LinkCard href="https://sourcegraph.com/contact/request-info" imgSrc="https://sourcegraph.com/.assets/img/sourcegraph-mark.svg" imgAlt="Cody Enterprise" title="Cody Enterprise" description="Get in touch with our team to try Cody for Sourcegraph Enterprise." />
 </LinkCards>
 
-## Cody Enterprise features
+## Setting up Cody Enterprise
 
-To cater to your Enterprise requirements, Cody offers the following features:
+You can set up Cody for your Enterprise instance by two methods:
 
-### IDE token expiry
+1. Sourcegraph Cloud
+2. Self-hosted Sourcegraph
 
-Site administrators can set the duration of access tokens for users connecting Cody from their IDEs (VS Code, JetBrains, etc.). This can be configured from the **Site admin** page of the Sourcegraph Enterprise instance. Available options include **7, 14, 30, 60, and 90 days**.
+## Cody on Sourcegraph Cloud
 
-![ide-token-expiry](https://storage.googleapis.com/sourcegraph-assets/Docs/token-expiry.png)
+With [Sourcegraph Cloud](/cloud/), you get Cody as a managed service, and you **do not** need to enable Cody as is required for self-hosted setup. However, by contacting your account manager, Cody can still be enabled or disabled on-demand on your Sourcegraph instance.
 
-### Guardrails
+## Self-hosted Sourcegraph Enterprise
 
-<Callout type= "note">Guardrails for public code is currently in Beta and is supported with VS Code and JetBrains IDEs extensions.</Callout>
+### Prerequisites
 
-Open source attribution guardrails for public code, commonly called copyright guardrails, reduce the exposure to copyrighted code. This involves implementing a verification mechanism within Cody to ensure that any code generated by the platform does not replicate open source code.
+- You have Sourcegraph version `5.1.0` or more
+- A Sourcegraph Enterprise subscription with [Cody Gateway](/cody/core-concepts/cody-gateway) or an account with a third-party LLM provider
 
-Guardrails for public code are available to all Sourcegraph Enterprise instances and are **disabled** by default. You can enable them from the Site configuration section by setting `attribution.enabled` to `true`.
+### Enable Cody on your Sourcegraph instance
 
-Guardrails don't differentiate between license types. It matches any code snippet that is at least **ten lines** long from the **290,000** indexed open source repositories.
+Site admins can only enable Cody on the Sourcegraph instance. To do so,
 
-### Admin controls
+- First, configure your desired LLM provider either by [using Sourcegraph Cody Gateway](/cody/core-concepts/cody-gateway) or by directly using a third-party LLM provider
+- Next, go to **Site admin > Site configuration** (`/site-admin/configuration`) on your instance and set:
 
-<Callout type="note">Admin controls are supported with VS Code and JetBrains IDE extension.</Callout>
+```json
+    {
+      // [...]
+      "cody.enabled": true,
+      "completions": {
+        "provider": "sourcegraph"
+      }
+    }
+```
 
-Site administrators have selective control over users' access to Cody Enterprise, which is managed via the Sourcegraph role-based access control system. This provides a more intuitive user interface for assigning permission to use Cody.
+- Cody is enabled on your self-hosted Sourcegraph enterprise instance
 
-### Analytics
+## Disable Cody
 
-<Callout type= "note">Cody Analytics are supported with VS Code IDE extension and on the latest versions of JetBrains IDEs.</Callout>
+To turn Cody off:
 
-Cody Enterprise users can view analytics for their instance. A separately managed cloud service for Cody analytics handles user auth, gets metrics data from Sourcegraph's BigQuery instance, and visualizes the metrics data.
+- Go to **Site admin > Site configuration** (`/site-admin/configuration`) on your instance and set:
 
-The following metrics are available for Cody Enterprise users:
+```json
+    {
+      // [...]
+      "cody.enabled": false
+    }
+```
 
-| **Metric Type** |                                                                                                                                           **What is measured?**                                                                                                                                            |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Active users    | - Total active users <br /> - Average daily users <br /> - Average no. of days each user used Cody (of last 30 days) <br /> - Cody users by day (last 30 days) <br /> - Cody users by month (last two months) <br /> - Cody users by number of days used                                                   |
-| Completions     | - Total accepted completions <br /> - Minutes saved per completion <br /> - Hours saved by completions <br /> - Cody completions by day <br /> - Completions acceptance rate <br /> - Weighted completions acceptance rate <br /> - Average completion latency <br /> - Acceptance rate by language <br /> |
-| Chat            | - Total chat events <br /> - Minutes saved per chat <br /> - Hours saved by chats <br /> - Cody chats by day                                                                                                                                                                                               |
-| Commands        | - Total command events <br /> - Minutes saved per command <br /> - Hours saved by commands <br /> - Cody commands by day <br /> - Most used commands                                                                                                                                                       |
+## Enable Cody only for some users
 
-To enable Cody Analytics:
+How to enable Cody only for _some_ users depends on what version of Sourcegraph you are running.
 
-- Create an account on [Sourcegraph Accounts](https://accounts.sourcegraph.com/)
-- A user already having a Sourcegraph.com account gets automatically migrated to Sourcegraph Accounts. Users can sign in to Cody Analytics using their email and password
-- Users without a Sourcegraph.com account should contact one of our team members. They can help with both the account setup and assigning instances to specific users
-- Map your user account to a Sourcegraph instance, and this gives you access to Cody analytics
+### Sourcegraph v5.3+
 
-### Multi-repository context
+In Sourcegraph v5.3+, access to Cody is managed via user roles. By default, all users have access.
 
-Cody supports multi-repository context, allowing you to search up to 10 repositories simultaneously for relevant information. Open a new chat, type `@`, and select `Remote Repositories.`
+First, ensure Cody is enabled in your site configuration. Go to **Site admin > Site configuration** (`/site-admin/configuration`) on your instance and set:
 
-Keep @-mentioning repos that you want to include in your context. This flexibility lets you get more comprehensive and accurate responses by leveraging information across multiple codebases.
+```json
+    {
+      // [...]
+      "cody.enabled": true,
+      // Make sure cody.restrictUsersFeatureFlag is not in your configuration! If it is, remove it.
+    }
+```
 
-### @-mention directory
+<Callout type="info"> Ensure `cody.restrictUsersFeatureFlag` is **not** in your site configuration. If it is, remove it or else the old feature-flag approach from Sourcegraph 5.2 and earlier will be used.</Callout>
 
-To better support teams working with large monorepos, Enterprise users can `@-mention` directories when chatting with Cody. This helps you define more specific directories and sub-directories within that monorepo to give more precise context.
+Next, go to **Site admin > Users & Auth > Roles** (`/site-admin/roles`) on your instance. On that page, you can:
 
-To do this, type `@` in the chat, and then select **Directories** to search other repositories for context in your codebase.
+- Control whether users **by default** have access to Cody (expand `User [System]` and toggle **Cody** > **Access** as desired)
+- Control whether groups of users have access to Cody (`+Create role` and enable the **Cody** > **Access** toggle as desired)
 
-![@-mention-directory](https://storage.googleapis.com/sourcegraph-assets/Docs/cody-ent-at-mention-dir-1124.png)
+### Sourcegraph v5.2 and earlier
 
-Please note that you can only `@-mention` remote directories (i.e., directories in your Sourcegraph instance) but not local directories. This means any recent changes to your directories can't be utilized as context until your Sourcegraph instance re-indexes any changes.
+In Sourcegraph v5.2 and earlier, you should use the feature flag `cody` to turn Cody on selectively for some users. To do so:
 
-If you want to include recent changes that haven't been indexed in your Sourcegraph instance, you can `@-mention` specific files, lines of code, or symbols.
+- Go to **Site admin > Site configuration** (`/site-admin/configuration`) on your instance and set:
 
-## Supported LLM models
+```json
+    {
+      // [...]
+      "cody.enabled": true,
+      "cody.restrictUsersFeatureFlag": true
+    }
+```
 
-Sourcegraph Enterprise supports different LLM providers and models, such as models from Anthropic and OpenAI. You can do this by adjusting your Sourcegraph instance configuration.
+- Next, go to **Site admin > Feature flags** (`/site-admin/feature-flags`)
+- Add a feature flag called `cody`
+- Select the `boolean` type and set it to `false`
+- Once added, click on the feature flag and use **add overrides** to pick users that will have access to Cody
 
-<FeatureParity type='ent' />
-For the supported LLM models listed above, refer to the following notes:
+![add-overrides](https://user-images.githubusercontent.com/25070988/235454594-9f1a6b27-6882-44d9-be32-258d6c244880.png)
 
-1. Microsoft Azure is planning to deprecate the APIs used in Sourcegraph version `>5.3.3` on July 1, 2024 [Source](https://learn.microsoft.com/en-us/azure/ai-services/openai/api-version-deprecation)
-2. Claude 2.1 is not recommended
-3. Sourcegraph doesn’t recommend using the GPT-4 (non-Turbo), Claude 1, or Claude 2 models anymore
-4. Only supported through legacy completions API
-5. BYOK (Bring Your Own Key) with managed services are only supported for Self-hosted Sourcegraph instances
-6. GPT-4 and GPT-4o for completions have a bug that is resulting in many failed completions
+## Configure Cody for LLM providers
 
-### Supported model configuration
+Cody supports several LLM providers and models. You can access these models via the Cody Gateway, directly using your own model provider account or infrastructure.
 
-Use the drop-down menu to make your desired selection and get a detailed breakdown of the supported model configuration for each provider on Cody Enterprise. This is an on-site configuration. Admins should pick a value from the table for `chatModel` to configure their chat model.
+There are two ways of configuring Cody for LLM providers:
 
-<FeatureParity type='configuration' />
+<QuickLinks>
 
-For the supported LLM model configuration listed above, refer to the following notes:
+<QuickLink title="Completions" icon='lightbulb' href="/cody/enterprise/completions-configuration" description="How to configure Cody using the completions." />
 
-1. Microsoft Azure is planning to deprecate the APIs used in Sourcegraph version `>5.3.3` on July 1, 2024 [Source](https://learn.microsoft.com/en-us/azure/ai-services/openai/api-version-deprecation)
-2. Claude 2.1 is not recommended
-3. Sourcegraph doesn't recommend GPT-4 non-turbo, Claude 1 or 2 models
-4. Only supported through legacy completions API
-5. BYOK (Bring Your Own Key) with managed services are only supported for Self-hosted Sourcegraph instances
+<QuickLink title="Model Configuration" icon='installation' href="/cody/enterprise/model-configuration" description="How to configure Cody using the model configuration." />
+
+</QuickLinks>