mirror of
https://github.com/sourcegraph/sourcegraph.git
synced 2026-02-06 17:31:43 +00:00
Add basic API doc, clean up links and stuff (#21727)
* Improve docs based on hallway test * Scaffold the contexts API page * Update heading level * Add search contexts API docs examples. Remove experimental from search contexts docs and fix links. * Fix links * Add link to API doc Co-authored-by: Rok <rok@sourcegraph.com>
This commit is contained in:
Quinn Keast
GitHub
parent
8369e6084e
commit
e60b77a1f1
2
client/extension-api/src/sourcegraph.d.ts
vendored
2
client/extension-api/src/sourcegraph.d.ts
vendored
@ -1253,7 +1253,7 @@ declare module 'sourcegraph' {
|
||||
* A search context is a set of repositories and revisions on a Sourcegraph instance.
|
||||
* When set, extensions use it to scope search queries, code intelligence actions, etc.
|
||||
*
|
||||
* See more information at https://docs.sourcegraph.com/code_search/explanations/features#search-contexts-experimental.
|
||||
* See more information at https://docs.sourcegraph.com/code_search/explanations/features#search-contexts.
|
||||
*/
|
||||
export const searchContext: string | undefined
|
||||
|
||||
|
||||
@ -61,7 +61,7 @@ function getHighlightTourStep(onClose: () => void): HTMLElement {
|
||||
</div>
|
||||
<div class="mt-2 mb-2">Search just the code you care about with search contexts.</div>
|
||||
<div>
|
||||
<a href="https://docs.sourcegraph.com/code_search/explanations/features#search-contexts-experimental" target="_blank">
|
||||
<a href="https://docs.sourcegraph.com/code_search/explanations/features#search-contexts" target="_blank">
|
||||
Learn more
|
||||
</a>
|
||||
</div>
|
||||
|
||||
@ -129,7 +129,7 @@ export const ConvertVersionContextsPage: React.FunctionComponent<ConvertVersionC
|
||||
<div className="text-muted">
|
||||
Convert existing version contexts defined in site config into search contexts.{' '}
|
||||
<a
|
||||
href="https://docs.sourcegraph.com/code_search/explanations/features#search-contexts-experimental"
|
||||
href="https://docs.sourcegraph.com/code_search/explanations/features#search-contexts"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
>
|
||||
|
||||
@ -52,7 +52,7 @@ export const AuthenticatedCreateSearchContextPage: React.FunctionComponent<Creat
|
||||
A search context represents a group of repositories at specified branches or revisions that will
|
||||
be targeted by search queries.{' '}
|
||||
<a
|
||||
href="https://docs.sourcegraph.com/code_search/explanations/features#search-contexts-experimental"
|
||||
href="https://docs.sourcegraph.com/code_search/explanations/features#search-contexts"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
>
|
||||
|
||||
@ -84,7 +84,7 @@ export const SearchContextsListPage: React.FunctionComponent<SearchContextsListP
|
||||
<p className="text-muted">
|
||||
Search code you care about with search contexts.{' '}
|
||||
<a
|
||||
href="https://docs.sourcegraph.com/code_search/explanations/features#search-contexts-experimental"
|
||||
href="https://docs.sourcegraph.com/code_search/explanations/features#search-contexts"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
>
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# How to convert version contexts to search contexts
|
||||
|
||||
This guide will provide steps for migrating from [version contexts](../../code_search/explanations/features.md#version-contexts-sunsetting) to [search contexts](../../code_search/explanations/features.md#search-contexts-experimental) on your private Sourcegraph instance.
|
||||
This guide will provide steps for migrating from [version contexts](../../code_search/explanations/features.md#version-contexts-sunsetting) to [search contexts](../../code_search/explanations/features.md#search-contexts) on your private Sourcegraph instance.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
|
||||
189
doc/api/graphql/managing-search-contexts-with-api.md
Normal file
189
doc/api/graphql/managing-search-contexts-with-api.md
Normal file
@ -0,0 +1,189 @@
|
||||
# Managing search contexts with the API
|
||||
|
||||
Learn how to manage [search contexts](../../code_search/how-to/search_contexts.md) on private Sourcegraph instances with the API. If you haven't used the API before, learn more about [the GraphQL API and how to use it](index.md).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* Search contexts and search context management are [enabled in global settings](../../code_search/explanations/features.md#search-contexts).
|
||||
|
||||
### Permissions and visibility overview
|
||||
|
||||
To read and write search contexts through the API you will need appropriate permissions. The permissions are determined based on the individual search context's namespace and its visibility (private or public).
|
||||
|
||||
**Read** permissions (view contents, use in searches):
|
||||
|
||||
* **Public** search contexts are available to everyone
|
||||
* Including unauthenticated users only on Sourcegraph Cloud
|
||||
* **Private** search contexts
|
||||
* With user namespace: only available to the user
|
||||
* With organization namespace: only available to users in the organization
|
||||
* With global (instance-level) namespace: only available to site-admins
|
||||
|
||||
**Write** permissions (create, update, delete):
|
||||
|
||||
* Site-admins have write access to all public search contexts and all global (instance-level) search contexts
|
||||
* A regular user has write access to its search contexts and its organization's search contexts
|
||||
|
||||
## Create a context
|
||||
|
||||
Below is a GraphQL query that creates a new search context. To populate the `searchContext.namespace` property, you will have to query the API beforehand to retrieve the user or organization ID.
|
||||
|
||||
If `searchContext.namespace` is not specified or `null` then the context is created in the global (instance-level) namespace.
|
||||
To specify search context repositories you will need their ids. Similar to the `namespace` property you will need to retrieve them from the API before creating the context.
|
||||
|
||||
```gql
|
||||
mutation CreateSearchContext(
|
||||
$searchContext: SearchContextInput!
|
||||
$repositories: [SearchContextRepositoryRevisionsInput!]!
|
||||
) {
|
||||
createSearchContext(searchContext: $searchContext, repositories: $repositories) {
|
||||
id
|
||||
spec
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Example variables:
|
||||
|
||||
```json
|
||||
{
|
||||
"searchContext": {
|
||||
"name": "MySearchContext",
|
||||
"description": "A description of my search context",
|
||||
"namespace": "user-id",
|
||||
"public": true
|
||||
},
|
||||
"repositories": [
|
||||
{
|
||||
"repositoryID": "repo-id",
|
||||
"revisions": ["main", "branch-1"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Read a single context
|
||||
|
||||
Below is a GraphQL query that fetches a single search context by ID.
|
||||
|
||||
```gql
|
||||
query ReadSearchContext($id: ID!) {
|
||||
node(id: $id) {
|
||||
... on SearchContext {
|
||||
id
|
||||
spec
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Example variables:
|
||||
|
||||
```json
|
||||
{ "id": "search-context-id" }
|
||||
```
|
||||
|
||||
## List available contexts
|
||||
|
||||
Below is a GraphQL query that fetches all available search contexts and allows filtering by multiple parameters. The `namespaces` array allows filtering by one or multiple namespace ids (user or organization id).
|
||||
To include global (instance-level) contexts you can specify `null` as one of the ids. If the `namespaces` array is omitted or empty, then no filtering by namespace is applied and all available contexts are returned.
|
||||
The `query` parameter allows filtering by search context spec.
|
||||
|
||||
```gql
|
||||
query ListSearchContexts(
|
||||
$first: Int!
|
||||
$after: String
|
||||
$query: String
|
||||
$namespaces: [ID]
|
||||
$orderBy: SearchContextsOrderBy
|
||||
$descending: Boolean
|
||||
) {
|
||||
searchContexts(
|
||||
first: $first
|
||||
after: $after
|
||||
query: $query
|
||||
namespaces: $namespaces
|
||||
orderBy: $orderBy
|
||||
descending: $descending
|
||||
) {
|
||||
nodes {
|
||||
id
|
||||
spec
|
||||
}
|
||||
pageInfo {
|
||||
hasNextPage
|
||||
endCursor
|
||||
}
|
||||
totalCount
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Example variables:
|
||||
|
||||
Query with these variables will return the first 50 search contexts ordered by search context `updatedAt` timestamp ascending. The results will be filtered to include only
|
||||
global contexts (`null`), `organization1` contexts (`organization1-id`), and `user1` contexts (`user1-id`).
|
||||
|
||||
```json
|
||||
{
|
||||
"first": 50,
|
||||
"namespaces": [null, "organization1-id", "user1-id"],
|
||||
"orderBy": "SEARCH_CONTEXT_UPDATED_AT",
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Update a context
|
||||
|
||||
Below is a GraphQL query that updates an existing search context. You cannot update a search context namespace.
|
||||
You have to provide the full search context and all repositories with revisions you want to keep on each update.
|
||||
|
||||
```gql
|
||||
mutation UpdateSearchContext(
|
||||
$id: ID!
|
||||
$searchContext: SearchContextEditInput!
|
||||
$repositories: [SearchContextRepositoryRevisionsInput!]!
|
||||
) {
|
||||
updateSearchContext(id: $id, searchContext: $searchContext, repositories: $repositories) {
|
||||
id
|
||||
spec
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Example variables:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "search-context-id-to-update",
|
||||
"searchContext": {
|
||||
"name": "MyUpdatedSearchContext",
|
||||
"description": "An updated description of my search context",
|
||||
"public": false
|
||||
},
|
||||
"repositories": [
|
||||
{
|
||||
"repositoryID": "repo-id",
|
||||
"revisions": ["main", "branch-1", "branch-2"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Delete a context
|
||||
|
||||
Below is a GraphQL query that deletes a search context by ID.
|
||||
|
||||
```gql
|
||||
mutation DeleteSearchContext($id: ID!) {
|
||||
deleteSearchContext(id: $id) {
|
||||
alwaysNil
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Example variables:
|
||||
|
||||
```json
|
||||
{ "id": "search-context-id-to-delete" }
|
||||
```
|
||||
@ -118,7 +118,7 @@ Indexing multiple branches will add additional resource requirements to Sourcegr
|
||||
|
||||
> NOTE: All revisions specified in version contexts are also indexed.
|
||||
|
||||
## Search contexts <span class="badge badge-primary">experimental</span>
|
||||
## Search contexts
|
||||
|
||||
Search contexts help you search the code you care about on Sourcegraph. A search context represents a set of repositories at specific revisions on a Sourcegraph instance that will be targeted by search queries by default.
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
|
||||
Note that you can search across a maximum of 50 repositories at once using Sourcegraph Cloud. To search across more than 50 repositories at once or to search your organization's internal code, [run your own Sourcegraph instance](../../../admin/install/index.md).
|
||||
|
||||
## Search contexts <span class="badge badge-primary">experimental</span>
|
||||
## Search contexts
|
||||
|
||||
>NOTE: This feature is still in active development.
|
||||
|
||||
|
||||
@ -22,7 +22,7 @@ You can also search across multiple contexts at once using the `OR` [boolean ope
|
||||
|
||||
**Note**: Creating search contexts is only supported on private Sourcegraph instances. Sourcegraph Cloud does not yet support custom search contexts. Want early access to custom contexts on Sourcegraph Cloud? [Let us know](mailto:feedback@sourcegraph.com).
|
||||
|
||||
When search contexts are [enabled on your private Sourcegraph instance](../explanations/features.md#search-contexts-experimental), you can create your own search contexts.
|
||||
When search contexts are [enabled on your private Sourcegraph instance](../explanations/features.md#search-contexts), you can create your own search contexts.
|
||||
|
||||
A search context consists of a name, description, and a set of repositories at one or many revisions.
|
||||
|
||||
@ -67,6 +67,10 @@ For example:
|
||||
|
||||
You will be returned to the list of search contexts. Your new search context will appear in the search contexts selector in the search input, and can be [used immediately](#using-search-contexts).
|
||||
|
||||
## Managing search contexts with the API
|
||||
|
||||
Learn how to [manage search contexts with the GraphQL API](../../api/graphql/managing-search-contexts-with-api.md).
|
||||
|
||||
## Search contexts on Sourcegraph Cloud
|
||||
|
||||
Please see [searching across repositories you've added to Sourcegraph Cloud with search contexts](./searching_with_search_contexts.md).
|
||||
Learn how to [search across repositories you've added to Sourcegraph Cloud with search contexts](./searching_with_search_contexts.md).
|
||||
|
||||
@ -48,7 +48,7 @@ Sourcegraph code search helps developers perform these tasks more quickly and ef
|
||||
- Search [commit diffs](explanations/features.md#commit-diff-search) and [commit messages](explanations/features.md#commit-message-search) to see how code has changed.
|
||||
- Narrow your search by repository and file pattern.
|
||||
- Define saved [search scopes](explanations/features.md#search-scopes) for easier searching.
|
||||
- Use [search contexts](explanations/features.md#search-contexts-experimental) to search across a set of repositories at specific revisions.
|
||||
- Use [search contexts](explanations/features.md#search-contexts) to search across a set of repositories at specific revisions.
|
||||
- Curate [saved searches](explanations/features.md#saved-searches) for yourself or your org.
|
||||
- Set up notifications for code changes that match a query.
|
||||
- View [language statistics](explanations/features.md#statistics) for search results.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user