Doc updates: mention the LSP server

Author: simonmar

glean/lsp/README.md

@@ -13,6 +13,7 @@ Glass, and currently provides the following LSP features:
 * Go to References
 * Type on Hover
 * Outline
+* Symbol Search
 
 More features may be added in the future.
 

glean/website/docs/building.md

@@ -5,24 +5,31 @@ sidebar_label: Building Glean
 ---
 
 import {OssOnly, FbInternalOnly} from 'internaldocs-fb-helpers';
+import {SrcFile,SrcFileLink} from '@site/utils';
 
 ## Introduction
 
-Glean is written mainly in [Haskell](http://www.haskell.org/), and
-makes heavy use of
-[Thrift](https://github.com/facebookincubator/hsthrift) for data
-communication and serialization, so these are the main dependencies
-that are needed for building Glean.
+First we'll need to install some dependencies, and then we can build
+Glean. You can either build the latest stable release (easiest), or
+build the current code from the repository (harder), both methods are
+explained below.
 
 ## You will need
 
 * Linux. The build is only tested on Linux so far; we hope to add
   support for other OSs in the future. We build on x86\_64 and arm64v8.
 
-* [GHC](https://www.haskell.org/ghc/). To see which versions Glean is tested with, check the current [ci.yml](https://github.com/facebookincubator/Glean/blob/master/.github/workflows/ci.yml) script. We recommend installing GHC using [ghcup](https://www.haskell.org/ghcup/).
+* A working Haskell build environment including
+  [GHC](https://www.haskell.org/ghc/) and Cabal. To see which versions
+  Glean is tested with, check the current
+  [ci.yml](https://github.com/facebookincubator/Glean/blob/master/.github/workflows/ci.yml)
+  script.
 
-* Cabal/cabal-install version 3.6 or later (older versions won't
-  work). As for GHC, install these using ghcup.
+We recommend installing GHC and Cabal using [ghcup](https://www.haskell.org/ghcup/):
+
+1. [Install ghcup](https://www.haskell.org/ghcup/)
+2. `ghcup install ghc 9.6.7`
+3. `ghcup install cabal`
 
 Additional per-distribution setup follows.
 
@@ -127,7 +134,7 @@ sudo dnf install \
 
 ## Build using Cabal
 
-Glean can be built and installed entirely using `cabal`, with:
+To build and install the latest stable version of Glean:
 
 ```
 cabal install glean
@@ -143,7 +150,7 @@ The schema source files will be installed somewhere under
 
 Installing with `cabal install` is sufficient if you want to:
 
-* Just try it out
+* Just try it out, e.g. with the generic LSP server.
 * Index some source code in a supported language
 * Run queries against a DB, perhaps produced by someone else
 * Run a server (including Glass)
@@ -153,6 +160,13 @@ If you want to make changes to the schema or work on Glean itself then
 you will likely need to build from source: continue to the next
 section.
 
+If you want to use the <SrcFileLink file="glean/lsp">generic LSP
+server</SrcFileLink>, build and install it with:
+
+```
+cabal install glean-lsp
+```
+
 ## Building from the repository
 
 Clone the repository:

glean/website/docs/docker.md

@@ -0,0 +1,128 @@
+---
+id: docker
+title: Using the Docker image
+sidebar_label: Using the Docker image
+---
+
+import {OssOnly, FbInternalOnly} from 'internaldocs-fb-helpers';
+import {SrcFile,SrcFileLink} from '@site/utils';
+
+
+:::warning
+
+The Docker image is currently not working; however building Glean from
+scratch is now significantly easier than it was in the past, so we
+recommend just heading over to [Building Glean from
+Source](building.md).
+
+:::
+
+We provide a Docker image containing a pre-built set of Glean binaries
+that you can try out.  These images are built automatically by a
+[Github Action](https://github.com/facebookincubator/Glean/blob/master/.github/workflows/glean-docker.yml).
+
+Pull the latest demo Docker image (warning, this is around 7GB):
+
+```
+docker pull ghcr.io/facebookincubator/glean/demo:latest
+```
+
+Run it:
+
+```
+docker run -it -p 8888:8888 ghcr.io/facebookincubator/glean/demo:latest
+```
+
+:::info
+
+What's in the image?
+
+* A build of Glean, in `/glean-code`
+* The [flow](https://github.com/facebook/flow/) binary, in `/usr/local/bin/flow`
+* A checkout of [react](https://github.com/facebook/react/) in `/react-code`
+* A Glean database containing the Flow index of React in `/gleandb`
+
+:::
+
+Start the Glean [shell](shell.md):
+
+```
+glean shell --db-root /glean-demo/db --schema /glean-demo/schema/source
+```
+
+You should see:
+
+```
+Glean Shell, built on <time>, from rev <unknown>
+type :help for help.
+>
+```
+
+The demo image contains a pre-generated database containing the
+results of running the Flow indexer on the React repository:
+
+```
+> :list
+react/0 (complete)
+  Created: 2021-05-24T02:42:33Z (30 days, 9 hours ago)
+```
+
+We can look at the contents:
+
+```
+react> :db react
+using database react/0
+react> :stat
+flow.Declaration.3
+  count: 26756
+  size:  888756 (867.93 kB) 4.8248%
+...
+Total size: 17.57 MB
+```
+
+## Running the server
+
+Above we showed the shell reading the database from the filesystem
+directly. Instead we can run a server that the clients will interact
+with to make queries:
+
+```
+glean-server --db-root /glean-demo/db --schema /glean-demo/schema/source --port 12345
+```
+
+And now the shell can connect to the server:
+
+```
+glean shell --service localhost:12345
+```
+
+The commands work exactly the same as with local databases, but now it
+would also work over the network.
+
+## Hyperlink demo
+
+We have a small demo showing how Glean can enable code navigation. The <SrcFileLink file="glean/demo/Hyperlink.hs">glean-hyperlink</SrcFileLink> tool
+creates a webserver that serves hyperlinked source code using data
+from a specified Glean database.
+
+We can navigate the React source code as follows. First start the
+Glean server:
+
+```
+glean-server --db-root /glean-demo/db --schema /glean-demo/schema/source --port 12345
+```
+
+Next start the Hyperlink server:
+
+```
+glean-hyperlink --service localhost:12345 --db react --root /react-code --http 8888
+```
+
+Now navigate to `http://localhost:8888` in your browser, and you
+should see a list of source files. Click on a file, and navigate
+around the code by clicking on a symbol reference to jump to its
+definition.  Try something substantial like
+`react-dom/src/client/ReactDOMComponent.js`
+(http://localhost:8888/packages/react-dom/src/client/ReactDOMComponent.js) -
+note how Glean is accurately linking both local and imported
+symbols.

glean/website/docs/introduction.md

@@ -20,6 +20,9 @@ If you found yourself here by mistake, go back to the
 
 </FbInternalOnly>
 
+Just want to get started and read the docs later? Jump to [Building
+Glean](building.md).
+
 ## Overview
 
 Glean is a system for working with facts about source code. It is
@@ -89,10 +92,27 @@ Glean consists of the following:
   language. Language-neutral abstractions can be built by <SrcFileLink
   file="glean/schema/source/codemarkup.angle">deriving facts using Angle</SrcFileLink>.
 
+* **<SrcFileLink file="glean/glass">Glass</SrcFileLink>**,
+  a language-agnostic symbol server. Glass is a server layer on top of
+  Glean that exposes an API for performing common language-independent
+  queries over Glean data, such as listing the symbols in a source
+  file. Glass can be used as the basis for language tools; in fact
+  Glass is used to power our Glean-based LSP server.
+
+* A **<SrcFileLink file="glean/lsp">generic LSP
+  server</SrcFileLink>**, built using Glean and Glass. This can be
+  used to browse a large codebase in [VS
+  Code](https://code.visualstudio.com/)[^3]: index the code using
+  Glean, and connect VS Code to the LSP server to provide common
+  code-navigation features such as go-to-definition, find-references,
+  and symbol search.
+
 [^1]: while we could in principle store the full AST, for efficiency
 reasons we typically store only the parts we need for the clients we
 want to support. Usually that means things like the locations of
 definitions and cross-references, but not expressions.
 
 [^2]: If you're familiar with Datalog, it's worth noting that
 currently Angle is limited to non-recursive queries only.
+
+[^3]: Or any IDE that supports LSP.

glean/website/docs/lsp.md

@@ -0,0 +1,22 @@
+---
+id: lsp
+title: Setting up the LSP server
+sidebar_label: Setting up the LSP server
+---
+
+import {OssOnly, FbInternalOnly} from 'internaldocs-fb-helpers';
+import {SrcFile,SrcFileLink} from '@site/utils';
+
+Glean comes with a generic LSP server that can be used for browsing
+large codebases in [VS Code](https://code.visualstudio.com/), or any
+IDE that supports the LSP protocol. This LSP server is intended to
+be used in a read-only way: it doesn't currently support updating
+the data if the source code is edited, but it can be useful for
+navigating a large codebase using familiar IDE features.
+
+The steps to set it up are:
+
+1. [Build and install Glean and glean-lsp](building.md)
+2. [Index your source code](indexer/intro.md) into a local DB
+2. Follow the instructions in `glean-lsp`'s <SrcFileLink
+file="glean/lsp/README.md">README.md</SrcFileLink> to set up the LSP server with VS Code, or your IDE.

glean/website/docs/trying.md

@@ -7,6 +7,15 @@ sidebar_label: Trying Glean
 import {OssOnly, FbInternalOnly} from 'internaldocs-fb-helpers';
 import {SrcFile,SrcFileLink} from '@site/utils';
 
+
+:::warning
+
+The Docker image is currently not working; however building Glean from
+scratch is now significantly easier than it was in the past, so we
+recommend just skipping ahead to [Building Glean from Source](building.md)
+
+:::
+
 We provide a Docker image containing a pre-built set of Glean binaries
 that you can try out.  These images are built automatically by a
 [Github Action](https://github.com/facebookincubator/Glean/blob/master/.github/workflows/glean-docker.yml).

glean/website/sidebars.js

@@ -19,9 +19,10 @@ module.exports = {
           ],
           external: [{
               'Quick Start': [
-                  'trying',
                   'building',
+                  'lsp',
                   'walkthrough',
+                  'docker',
               ]
           }],
       }),