Skip to content

Commit ee42d28

Browse files
varungandhi-srcvarungandhi-src
authored
docs: Rework README to mention indexers. (#101)
1 parent fa35ed5 commit ee42d28

File tree

3 files changed

+136
-123
lines changed

3 files changed

+136
-123
lines changed

‎Readme.md

Lines changed: 20 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ This repository includes:
1111
- Rich Go bindings for SCIP: This includes many utility functions
1212
to help build tooling on top of SCIP.
1313
- Auto-generated bindings for TypeScript, Rust and Haskell.
14-
- The [`scip` CLI](#scip-cli-reference) makes SCIP indexes
14+
- The [`scip` CLI](./docs/CLI.md) makes SCIP indexes
1515
a breeze to work with.
1616

1717
If you're interested in better understanding the motivation behind SCIP,
@@ -30,138 +30,37 @@ Also, check out the [Debugging section][] in the Development docs.
3030

3131
[debugging section]: ./Development.md#debugging
3232

33-
## Contributing
33+
## Tools using SCIP
3434

35-
We welcome questions, suggestions as well as code and docs contributions.
35+
Several indexers currently emit SCIP data:
36+
[scip-java](https://github.com/sourcegraph/scip-java) (for Java, Kotlin and Scala),
37+
[scip-typescript](https://github.com/sourcegraph/scip-typescript),
38+
[scip-python](https://github.com/sourcegraph/scip-python),
39+
[scip-ruby](https://github.com/sourcegraph/scip-ruby) and
40+
[rust-analyzer](https://github.com/sourcegraph/rust-analyzer).
3641

37-
For submitting contributions, check out [Development.md](./Development.md)
38-
to better understand project structure and common workflows.
42+
For more details about indexers, including LSIF-based indexers,
43+
see the [Sourcegraph documentation](https://docs.sourcegraph.com/code_navigation/references/indexers).
3944

40-
Contributors should abide by the [Sourcegraph Code of Conduct](https://handbook.sourcegraph.com/company-info-and-process/communication/code_of_conduct/).
45+
Other tools which use SCIP include the [Sourcegraph CLI](https://github.com/sourcegraph/src-cli),
46+
and the SCIP CLI in this repo.
4147

42-
## Installing CLI
48+
## Installing the `scip` CLI
4349

44-
You can find binaries for `scip`
45-
[here](https://github.com/sourcegraph/scip/releases). If you'd like to create a
46-
binary locally you can do so with:
50+
You can find binaries for the `scip` CLI tool [here](https://github.com/sourcegraph/scip/releases).
51+
You can also compile a binary locally using:
4752

4853
```sh
4954
git clone https://github.com/sourcegraph/scip.git --depth=1
5055
cd scip
5156
go build -o scip ./cmd
5257
```
5358

54-
## SCIP CLI reference
55-
56-
```
57-
NAME:
58-
scip - SCIP Code Intelligence Protocol CLI
59-
60-
USAGE:
61-
scip [global options] command [command options] [arguments...]
62-
63-
VERSION:
64-
v0.2.1-git
65-
66-
DESCRIPTION:
67-
For more details, see the project README at:
68-
69-
https://github.com/sourcegraph/scip
70-
71-
COMMANDS:
72-
convert Convert a SCIP index to an LSIF index
73-
lint Flag potential issues with a SCIP index
74-
print Print a SCIP index in a human-readable format for debugging
75-
snapshot Generate snapshot files for golden testing
76-
stats Output useful statistics about a SCIP index
77-
help, h Shows a list of commands or help for one command
78-
79-
GLOBAL OPTIONS:
80-
--help, -h show help (default: false)
81-
--version, -v print the version (default: false)
82-
```
83-
84-
### `scip convert`
85-
86-
```
87-
NAME:
88-
scip convert - Convert a SCIP index to an LSIF index
89-
90-
USAGE:
91-
scip convert [command options] [arguments...]
92-
93-
OPTIONS:
94-
--from value Path to SCIP index file (default: index.scip)
95-
--to value Output path for LSIF index (default: dump.lsif)
96-
```
97-
98-
### `scip lint`
99-
100-
```
101-
NAME:
102-
scip lint - Flag potential issues with a SCIP index
103-
104-
USAGE:
105-
scip lint [command options] [arguments...]
106-
107-
DESCRIPTION:
108-
Example usage:
109-
110-
scip lint /path/to/index.scip
111-
112-
You may want to filter the output using `grep -v <pattern>`
113-
to narrow down on certain classes of errors.
114-
115-
OPTIONS:
116-
--help, -h show help (default: false)
117-
```
118-
119-
### `scip print`
120-
121-
```
122-
NAME:
123-
scip print - Print a SCIP index in a human-readable format for debugging
124-
125-
USAGE:
126-
scip print [command options] [arguments...]
127-
128-
DESCRIPTION:
129-
WARNING: The output may change over time.
130-
Do not rely on the output of this command in scripts
131-
132-
OPTIONS:
133-
--help, -h show help (default: false)
134-
```
135-
136-
### `scip snapshot`
137-
138-
```
139-
NAME:
140-
scip snapshot - Generate snapshot files for golden testing
141-
142-
USAGE:
143-
scip snapshot [command options] [arguments...]
144-
145-
DESCRIPTION:
146-
The snapshot subcommand generates snapshot files which
147-
can be use for inspecting the output of an index in a
148-
visual way. Occurrences are marked with caret signs (^)
149-
and symbol information.
150-
151-
OPTIONS:
152-
--from value Path to SCIP index file (default: index.scip)
153-
--to value Path to output directory for snapshot files (default: scip-snapshot)
154-
```
155-
156-
### `scip stats`
59+
## Contributing
15760

158-
```
159-
NAME:
160-
scip stats - Output useful statistics about a SCIP index
61+
We welcome questions, suggestions as well as code and docs contributions.
16162

162-
USAGE:
163-
scip stats [command options] [arguments...]
63+
For submitting contributions, check out [Development.md](./Development.md)
64+
to better understand project structure and common workflows.
16465

165-
OPTIONS:
166-
--from value Path to SCIP index file (default: index.scip)
167-
```
66+
Contributors should abide by the [Sourcegraph Code of Conduct](https://handbook.sourcegraph.com/company-info-and-process/communication/code_of_conduct/).

‎cmd/main_test.go

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,9 @@ import (
1919
"github.com/sourcegraph/scip/cmd/tests/reprolang/bindings/go/repro"
2020
)
2121

22-
func TestReadmeInSync(t *testing.T) {
22+
func TestCLIReferenceInSync(t *testing.T) {
2323
app := scipApp()
24-
readmeBytes, err := os.ReadFile(filepath.Join("..", "Readme.md"))
24+
readmeBytes, err := os.ReadFile(filepath.Join("..", "docs", "CLI.md"))
2525
require.Nil(t, err)
2626
readme := string(readmeBytes)
2727

‎docs/CLI.md

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# SCIP CLI Reference
2+
3+
```
4+
NAME:
5+
scip - SCIP Code Intelligence Protocol CLI
6+
7+
USAGE:
8+
scip [global options] command [command options] [arguments...]
9+
10+
VERSION:
11+
v0.2.1-git
12+
13+
DESCRIPTION:
14+
For more details, see the project README at:
15+
16+
https://github.com/sourcegraph/scip
17+
18+
COMMANDS:
19+
convert Convert a SCIP index to an LSIF index
20+
lint Flag potential issues with a SCIP index
21+
print Print a SCIP index in a human-readable format for debugging
22+
snapshot Generate snapshot files for golden testing
23+
stats Output useful statistics about a SCIP index
24+
help, h Shows a list of commands or help for one command
25+
26+
GLOBAL OPTIONS:
27+
--help, -h show help (default: false)
28+
--version, -v print the version (default: false)
29+
```
30+
31+
## `scip convert`
32+
33+
```
34+
NAME:
35+
scip convert - Convert a SCIP index to an LSIF index
36+
37+
USAGE:
38+
scip convert [command options] [arguments...]
39+
40+
OPTIONS:
41+
--from value Path to SCIP index file (default: index.scip)
42+
--to value Output path for LSIF index (default: dump.lsif)
43+
```
44+
45+
## `scip lint`
46+
47+
```
48+
NAME:
49+
scip lint - Flag potential issues with a SCIP index
50+
51+
USAGE:
52+
scip lint [command options] [arguments...]
53+
54+
DESCRIPTION:
55+
Example usage:
56+
57+
scip lint /path/to/index.scip
58+
59+
You may want to filter the output using `grep -v <pattern>`
60+
to narrow down on certain classes of errors.
61+
62+
OPTIONS:
63+
--help, -h show help (default: false)
64+
```
65+
66+
## `scip print`
67+
68+
```
69+
NAME:
70+
scip print - Print a SCIP index in a human-readable format for debugging
71+
72+
USAGE:
73+
scip print [command options] [arguments...]
74+
75+
DESCRIPTION:
76+
WARNING: The output may change over time.
77+
Do not rely on the output of this command in scripts
78+
79+
OPTIONS:
80+
--help, -h show help (default: false)
81+
```
82+
83+
## `scip snapshot`
84+
85+
```
86+
NAME:
87+
scip snapshot - Generate snapshot files for golden testing
88+
89+
USAGE:
90+
scip snapshot [command options] [arguments...]
91+
92+
DESCRIPTION:
93+
The snapshot subcommand generates snapshot files which
94+
can be use for inspecting the output of an index in a
95+
visual way. Occurrences are marked with caret signs (^)
96+
and symbol information.
97+
98+
OPTIONS:
99+
--from value Path to SCIP index file (default: index.scip)
100+
--to value Path to output directory for snapshot files (default: scip-snapshot)
101+
```
102+
103+
## `scip stats`
104+
105+
```
106+
NAME:
107+
scip stats - Output useful statistics about a SCIP index
108+
109+
USAGE:
110+
scip stats [command options] [arguments...]
111+
112+
OPTIONS:
113+
--from value Path to SCIP index file (default: index.scip)
114+
```

0 commit comments

Comments
 (0)