Skip to content

Commit a8515fe

Browse files
olafurpgolafurpg
committed
Add documentation website
Previously, lsif-java didn't have any documentation for end-users. We only had documentation for contributors. This commit adds a website that includes user-facing documentation on how to run lsif-java with automatic indexing and manual indexing.
1 parent 756563f commit a8515fe

File tree

23 files changed

+699
-53
lines changed

23 files changed

+699
-53
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ jobs:
1212
- uses: olafurpg/setup-scala@v10
1313
- uses: actions/setup-go@v2
1414
with:
15-
go-version: '^1.13.1'
15+
go-version: "^1.13.1"
1616
- run: go get github.com/sourcegraph/lsif-semanticdb/cmd/lsif-semanticdb
1717
- run: sbt test
1818
check:

‎.github/workflows/mdoc.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
name: Website
2+
on:
3+
push:
4+
branches: [master, documentation-website]
5+
tags: ["*"]
6+
jobs:
7+
publish:
8+
runs-on: ubuntu-latest
9+
steps:
10+
- uses: actions/checkout@v2
11+
- uses: olafurpg/setup-scala@v10
12+
- run: sbt docs/docusaurusPublishGhpages
13+
env:
14+
GIT_DEPLOY_KEY: ${{ secrets.GIT_DEPLOY_KEY }}

‎.github/workflows/native.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ jobs:
3030
- name: sbt nativeImage
3131
shell: bash
3232
run: |
33-
sbt cli/nativeImage "cli/nativeImageRun --cwd tests/gradle-example"
33+
sbt cli/nativeImage "cli/nativeImageRun --cwd tests/gradle-example index"
3434
- uses: actions/upload-artifact@master
3535
with:
3636
path: ${{ matrix.local_path }}

‎README.md‎

Lines changed: 6 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,10 @@
1-
# Java LSIF indexer ![](https://img.shields.io/badge/status-development-yellow?style=flat)
2-
3-
Visit https://lsif.dev/ to learn about LSIF.
1+
# Java indexer for the Language Server Index Format (LSIF) ![](https://img.shields.io/badge/status-development-yellow?style=flat)
42

53
## Usage
64

7-
⚠️ This project is under development so there is nothing to try out at the
8-
moment.
9-
10-
### Supported tools and versions
11-
12-
Currently, only Java 8 with the build tool sbt is supported. We hope to increase
13-
compatibility with more Java language versions and build tools as the project
14-
evolves.
15-
16-
| Language version | Support |
17-
| ---------------- | --------------------------------- |
18-
| Java 7 | ❌ |
19-
| Java 8 | ✅ |
20-
| Java 11 | ✅ |
21-
| Java 12 | Not tested in CI, but should work |
22-
| Java 13 | Not tested in CI, but should work |
23-
| Java 14 | Not tested in CI, but should work |
24-
| Java 15 | ✅ |
25-
| Java 16 | Not tested in CI, but should work |
26-
| Java 17 | Not tested in CI, but should work |
27-
28-
| Build tool | Support |
29-
| ---------- | ------- |
30-
| Gradle | ✅ |
31-
| Maven | ✅ |
32-
| Bazel | ❌ |
33-
| Buck | ❌ |
34-
| sbt | ✅ |
5+
Visit https://sourcegraph.github.io/lsif-java to get started with lsif-java.
6+
7+
⚠ The rest of this readme is targeted at contributors to the lsif-java codebase.
358

369
## Overview
3710

@@ -130,6 +103,8 @@ These are the main components of the project.
130103
| `snapshots/test` | sbt | Runs all snapshot tests. |
131104
| `snapshots/run` | sbt | Update snapshot tests. Use this command after you have fixed a bug. |
132105
| `cli/run --cwd DIRECTORY` | sbt | Run `lsif-java` command-line tool against a given Gradle/Maven build. |
106+
| `cd website && yarn install && yarn start` | terminal | Start live-reload preview of the website at http://localhost:3000/lsif-java. |
107+
| `docs/mdoc --watch` | sbt | Re-generate markdown files in the `docs/` directory. |
133108
| `fixAll` | sbt | Run Scalafmt, Scalafix and Javafmt on all sources. Run this before opening a PR. |
134109

135110
### Import the project into IntelliJ

‎build.sbt‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ commands +=
5959
commands +=
6060
Command.command("checkAll") { s =>
6161
"scalafmtCheckAll" :: "scalafmtSbtCheck" :: "scalafixAll --check" ::
62-
"javafmtCheckAll" :: "publishLocal" :: s
62+
"javafmtCheckAll" :: "publishLocal" :: "docs/docusaurusCreateSite" :: s
6363
}
6464

6565
lazy val agent = project
@@ -293,3 +293,19 @@ lazy val fatjarPackageSettings = List[Def.Setting[_]](
293293
slimJar
294294
}
295295
)
296+
297+
lazy val docs = project
298+
.in(file("lsif-java-docs"))
299+
.settings(
300+
mdocOut :=
301+
baseDirectory.in(ThisBuild).value / "website" / "target" / "docs",
302+
fork := false,
303+
mdocVariables :=
304+
Map[String, String](
305+
"VERSION" -> version.value,
306+
"SCALA_VERSION" -> scalaVersion.value,
307+
"STABLE_VERSION" -> version.value.replaceFirst("\\-.*", "")
308+
)
309+
)
310+
.dependsOn(unit)
311+
.enablePlugins(DocusaurusPlugin)

‎cli/src/main/scala/com/sourcegraph/lsif_java/IndexCommand.scala‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,24 @@ import moped.annotations.Description
99
import moped.annotations.ExampleValue
1010
import moped.annotations.Inline
1111
import moped.annotations.TrailingArguments
12+
import moped.annotations.Usage
1213
import moped.cli.Application
1314
import moped.cli.Command
1415
import moped.cli.CommandParser
1516
import moped.internal.reporters.Levenshtein
1617
import os.CommandResult
1718
import os.Inherit
1819
import os.Shellable
20+
import moped.annotations.ExampleUsage
21+
import moped.annotations.CommandName
1922

2023
@Description(
21-
"Generates an LSIF index for the Java build of a provided workspace directory."
24+
"Automatically generate an LSIF index in the current working directory."
25+
)
26+
@Usage("lsif-java index [OPTIONS ...] -- [TRAILING_ARGUMENTS ...]")
27+
@ExampleUsage(
28+
"""|# Running the `index` command with no flags should work most of the time.
29+
|$ lsif-java index""".stripMargin
2230
)
2331
case class IndexCommand(
2432
@Description("The path where to generate the LSIF index.") output: Path =
@@ -41,12 +49,12 @@ case class IndexCommand(
4149
)
4250
@ExampleValue("Gradle") buildTool: Option[String] = None,
4351
@Description(
44-
"Whether to enable remove generated temporary files on exit."
52+
"Whether to remove generated temporary files on exit."
4553
) cleanup: Boolean = true,
4654
@Description(
47-
"The build command to use to compile all sources. " +
55+
"Optional. The build command to use to compile all sources. " +
4856
"Defaults to a build-specific command. For example, the default command for Maven command is 'clean verify -DskipTests'." +
49-
"To override the default, pass in the build command after a double dash: 'lsif-java -- compile'"
57+
"To override the default, pass in the build command after a double dash: 'lsif-java index -- compile test:compile'"
5058
)
5159
@TrailingArguments() buildCommand: List[String] = Nil,
5260
@Inline

‎cli/src/main/scala/com/sourcegraph/lsif_java/IndexSemanticdbCommand.scala‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
package com.sourcegraph.lsif_java
2+
3+
import moped.cli.Command
4+
import java.nio.file.Path
5+
import moped.annotations.Description
6+
import moped.annotations.PositionalArguments
7+
import moped.annotations.ExampleUsage
8+
import moped.annotations.Usage
9+
import moped.annotations.Inline
10+
import moped.cli.Application
11+
import scala.collection.mutable.ListBuffer
12+
import os.Shellable
13+
import os.Inherit
14+
import moped.cli.CommandParser
15+
import moped.annotations.CommandName
16+
17+
@Description("Converts SemanticDB files into a single LSIF index file.")
18+
@Usage("lsif-java index-semanticdb [OPTIONS ...] [POSITIONAL ARGUMENTS ...]")
19+
@ExampleUsage(
20+
"lsif-java index-semanticdb --out=myindex.lsif my/targetroot1 my/targetroot2"
21+
)
22+
@CommandName("index-semanticdb")
23+
final case class IndexSemanticdbCommand(
24+
@Description(
25+
"The name of the output file. Defaults to 'dump.lsif'"
26+
) out: Option[Path] = None,
27+
@Description(
28+
"SemanticDB file paths or directories that contain SemanticDB files."
29+
)
30+
@PositionalArguments() directories: List[Path] = Nil,
31+
@Inline() app: Application = Application.default
32+
) extends Command {
33+
def run(): Int = {
34+
val arguments = ListBuffer.empty[String]
35+
arguments += "lsif-semanticdb"
36+
out.foreach { dir =>
37+
arguments += s"--out=$dir"
38+
}
39+
directories.foreach { dir =>
40+
arguments += s"--semanticdbDir=$dir"
41+
}
42+
app.info(arguments.mkString(" "))
43+
app
44+
.process(Shellable(arguments.toList))
45+
.call(check = false, stderr = Inherit, stdout = Inherit)
46+
.exitCode
47+
}
48+
}
49+
50+
object IndexSemanticdbCommand {
51+
val default = IndexSemanticdbCommand()
52+
implicit val parser = CommandParser.derive(default)
53+
}

‎cli/src/main/scala/com/sourcegraph/lsif_java/LsifJava.scala‎

Lines changed: 22 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,35 @@
11
package com.sourcegraph.lsif_java
22

3+
import java.io.PrintStream
4+
35
import moped.cli.Application
46
import moped.cli.CommandParser
57
import moped.commands.HelpCommand
68
import moped.commands.VersionCommand
9+
import moped.reporters.Tput
710

811
object LsifJava {
9-
val app: Application = Application
10-
.fromName(
11-
binaryName = "lsif-java",
12-
BuildInfo.version,
13-
List(
14-
CommandParser[HelpCommand],
15-
CommandParser[VersionCommand],
16-
CommandParser[IndexCommand]
17-
)
12+
val app: Application = Application.fromName(
13+
binaryName = "lsif-java",
14+
BuildInfo.version,
15+
List(
16+
CommandParser[HelpCommand],
17+
CommandParser[VersionCommand],
18+
CommandParser[IndexCommand],
19+
CommandParser[IndexSemanticdbCommand]
1820
)
19-
.withIsSingleCommand(true)
21+
)
2022
def main(args: Array[String]): Unit = {
2123
app.runAndExitIfNonZero(args.toList)
2224
}
25+
26+
def printHelp(out: PrintStream): Unit = {
27+
out.println("```text")
28+
out.println("$ lsif-java index --help")
29+
val newApp = app
30+
.withTput(Tput.constant(100))
31+
.withEnv(app.env.withStandardOutput(out))
32+
newApp.run(List("index", "--help"))
33+
out.println("```")
34+
}
2335
}

‎docs/getting-started.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
id: getting-started
3+
title: Getting started
4+
---
5+
6+
By following the instructions on this page, you should be able to generate an
7+
[LSIF](https://microsoft.github.io/language-server-protocol/specifications/lsif/0.5.0/specification/)
8+
index of your Java codebase.
9+
10+
## Install `lsif-java`
11+
12+
The easiest way to install `lsif-java` is to download the native binary.
13+
14+
### Native binary
15+
16+
The native binary is only available for Linux and macOS. The native binary
17+
includes all dependencies and does not need further access to the internet after
18+
it's been downloaded.
19+
20+
```sh
21+
# macOS
22+
curl -Lo lsif-java https://github.com/sourcegraph/lsif-java/releases/download/@STABLE_VERSION@/lsif-java-x86_64-apple-darwin
23+
chmod +x lsif-java
24+
./lsif-java --help
25+
26+
# Linux
27+
curl -Lo lsif-java https://github.com/sourcegraph/lsif-java/releases/download/@STABLE_VERSION@/lsif-java-x86_64-pc-linux
28+
chmod +x lsif-java
29+
./lsif-java --help
30+
```
31+
32+
### Java launcher
33+
34+
Use [Coursier](https://get-coursier.io/docs/cli-installation.html) to launch the
35+
Java binary. The Java binary should work with any version of Java 8 or newer.
36+
37+
```sh
38+
# Homebrew
39+
brew install coursier/formulas/coursier
40+
coursier launch com.sourcegraph:lsif-java_2.13:@STABLE_VERSION@ -- --help
41+
42+
# macOS/Linux
43+
curl -fLo coursier https://git.io/coursier-cli
44+
chmod +x coursier
45+
./coursier launch com.sourcegraph:lsif-java_2.13:@STABLE_VERSION@ -- --help
46+
47+
# Windows
48+
bitsadmin /transfer downloadCoursierCli https://git.io/coursier-cli "%cd%\coursier"
49+
bitsadmin /transfer downloadCoursierBat https://git.io/coursier-bat "%cd%\coursier.bat"
50+
./coursier launch com.sourcegraph:lsif-java_2.13:@STABLE_VERSION@ -- --help
51+
```
52+
53+
### Java fat jar
54+
55+
Use the Coursier `bootstrap` command to generate a standalone Java binary, which
56+
includes all dependencies and does not require further access to the internet
57+
after installation.
58+
59+
```sh
60+
# macOS/Linux/Windows
61+
cs bootstrap --standalone -o lsif-java com.sourcegraph:lsif-java_2.13:@STABLE_VERSION@
62+
./lsif-java --help
63+
```
64+
65+
### Java library
66+
67+
The `lsif-java` command-line interface is published to Maven Central. You can
68+
run the command-line interface as a library by directly invoking the `main()`
69+
method on the `com.sourcegraph.lsif_java.LsifJava` class.
70+
71+
[![](https://img.shields.io/maven-central/v/com.sourcegraph/lsif-java_2.13)](https://repo1.maven.org/maven2/com/sourcegraph/lsif-java_2.13/)
72+
73+
If you're using Gradle.
74+
75+
```groovy
76+
implementation group: 'com.sourcegraph', name: 'lsif-java_2.13', version: '@STABLE_VERSION@'
77+
```
78+
79+
If you're using Maven.
80+
81+
```xml
82+
<dependency>
83+
<groupId>com.sourcegraph</groupId>
84+
<artifactId>lsif-java_2.13</artifactId>
85+
<version>@STABLE_VERSION@</version>
86+
</dependency>
87+
```
88+
89+
If you're using sbt.
90+
91+
```scala
92+
scalaVersion := "@SCALA_VERSION@" // Only Scala 2.13 is supported.
93+
libraryDependencies += "com.sourcegraph" %% "lsif-java" % "@STABLE_VERSION@"
94+
```
95+
96+
## Run `lsif-java index`
97+
98+
Run `lsif-java index --help` to see the available command-line options.
99+
100+
```scala mdoc:passthrough
101+
com.sourcegraph.lsif_java.LsifJava.printHelp(Console.out)
102+
```
103+
104+
## Supported Java versions
105+
106+
The `lsif-java` indexer is implemented as a Java compiler plugin that runs as
107+
part of your regular compilation in the build tool. By using Java compiler APIs,
108+
`lsif-java` is able to support a broad range of Java versions.
109+
110+
| Language version | Support |
111+
| ---------------- | ------------------------------ |
112+
| Java 7 | ❌ |
113+
| Java 8 | ✅ |
114+
| Java 11 | ✅ |
115+
| Java 12 | Not tested in CI, but may work |
116+
| Java 13 | Not tested in CI, but may work |
117+
| Java 14 | Not tested in CI, but may work |
118+
| Java 15 | ✅ |
119+
| Java 16 | Not tested in CI, but may work |
120+
| Java 17 | Not tested in CI, but may work |
121+
122+
## Supported build tools
123+
124+
Please open an issue if your build tool is not listed in the table below. Feel
125+
free to subscribe to the tracking issues to receive updates on your build tool.
126+
127+
| Build tool | Support | Tracking issue |
128+
| ---------- | ------- | -------------------------------------------------------------------------------- |
129+
| Gradle | ✅ | |
130+
| Maven | ✅ | |
131+
| Bazel | ❌ | [sourcegraph/lsif-java#88](https://github.com/sourcegraph/lsif-java/issues/88) |
132+
| Buck | ❌ | [sourcegraph/lsif-java#99](https://github.com/sourcegraph/lsif-java/issues/99) |
133+
| sbt | ❌ | [sourcegraph/lsif-java#110](https://github.com/sourcegraph/lsif-java/issues/110) |
134+
135+
**✅**: automatic indexing is fully supported. Please report a bug if the
136+
`lsif-java index` command does not work on your codebase.
137+
138+
**❌**: automatic inference is not supported but (!) you may still be able to
139+
use `lsif-java` by configuring it manually using the instructions
140+
[here](manual-configuration.md).

0 commit comments

Comments
 (0)