Added more detailed documentation for clangd

[gribozavr]

Summary

The text was written mostly by Sam McCall, screenshots are mostly made
by me.

[ilya-biryukov]

Still looking at it, a few quick notes.
Also added ioeric for an extra pair of eyes (it's a large change!).

clang-tools-extra/docs/clangd/Installation.rst

360 ↗

(On Diff #188513)

I'd avoid mentioning it at all, we didn't vet it for the 8 release (and I believe we landed critical fixes after the release cut).
We could add it back during 9.0 release.

clang-tools-extra/docs/clangd/index.rst

20 ↗

(On Diff #188513)

The original "clangd is a language server" looked somewhat better.
Having a link to the LSP website is a good bet, though.

[gribozavr]

clang-tools-extra/docs/clangd/Installation.rst

360 ↗

(On Diff #188513)

Removed in this patch (that I plan to cherry-pick into the 8.0 release branch). Will re-add in a separate patch, so that it goes into 9.0.

clang-tools-extra/docs/clangd/index.rst

20 ↗

(On Diff #188513)

Reworded to add the phrase "language server".

[gribozavr]

Addressed review comments

[gribozavr]

clang-tools-extra/docs/clangd/Installation.rst

360 ↗

(On Diff #188513)

Reverted back after offline discussion.

[gribozavr]

.

[gribozavr]

Added custom CSS for the details tag.

[ilya-biryukov]

clang-tools-extra/docs/clangd/Features.rst

41 ↗

(On Diff #188531)

It feels wrong to have announcements of the 9.0 features in the 8.0 release.
Maybe remove these. WDYT?

[ilya-biryukov]

It feels we have two groups of docs here, do you think it would be useful to split them more explicitly?
Specifically, we have:

1. User documentation
   • Getting started with clangd
   • Features
2. Developer documentation
   • Protocol extensions
   • Compiling clangd
   • Contributing to clangd

And the split is somewhat implicit right now

[gribozavr]

Separated user and developer documentation

[gribozavr]

.

[ilya-biryukov]

LGTM!

[gribozavr]

Removed mentions of clangd v9.

[thakis]

clang-tools-extra/trunk/docs/clangd/Installation.rst

325

Isn't the order of the arguments the wrong way round here?

[kadircet]

clang-tools-extra/trunk/docs/clangd/Installation.rst

325

yeah that seems to be the case it should rather be

$ ln -s ~/myproject-build/compile_commands.json ~/myproject/

sending out a patch, thanks for bringing it up!

clang-tools-extra/trunk/docs/_static/clang-tools-extra-styles.css

+details {
+  background-color: rgba(50, 150, 220, 0.08);
+  margin-bottom: 0.5em;
+  padding: 0 1em;
+  overflow-y: hidden; /* Suppress margin-collapsing */
+}
+details[open] {
+  border-bottom: 1px solid rgba(0, 0, 128, 0.2);
+  margin-bottom: 1em;
+}
+details summary {
+  font-weight: bold;
+  background-color: rgba(50, 150, 220, 0.1);
+  border-color: rgba(0, 0, 128, 0.2);
+  border-width: 1px;
+  border-style: solid none;
+  padding: 0.2em;
+  margin: 0 -1em;
+}
+details summary:hover {
+  background-color: rgba(50, 150, 220, 0.2);
+  cursor: pointer;
+}

clang-tools-extra/trunk/docs/_templates/layout.html

+{% extends "!layout.html" %}
+
+{% set css_files = css_files + ['_static/clang-tools-extra-styles.css'] %}

clang-tools-extra/trunk/docs/clangd/DeveloperDocumentation.rst

+==================================
+Developer documentation for clangd
+==================================
+
+.. toctree::
+   :maxdepth: 1
+
+   Extensions
+
+Compiling clangd
+================
+
+To build clangd from source, please follow the instructions for `building Clang
+<https://clang.llvm.org/get_started.html>`_ and include LLVM, Clang, and the
+"extra Clang tools" in your build.
+
+Contributing to clangd
+======================
+
+A good place for interested contributors is the `Clangd developer mailing list
+<https://lists.llvm.org/mailman/listinfo/clangd-dev>`_. For discussions with
+the broader community on topics not only related to Clangd, use `Clang
+developer mailing list <https://lists.llvm.org/mailman/listinfo/cfe-dev>`_.  If
+you're also interested in contributing patches to clangd, take a look at the
+`LLVM Developer Policy <https://llvm.org/docs/DeveloperPolicy.html>`_ and `Code
+Reviews <https://llvm.org/docs/Phabricator.html>`_ page. Contributions of new
+features to the `Language Server Protocol
+<https://github.com/Microsoft/language-server-protocol>`_ itself would also be
+very useful, so that clangd can eventually implement them in a conforming way.

clang-tools-extra/trunk/docs/clangd/Extensions.rst

+===================
+Protocol extensions
+===================
+
+clangd supports some features that are not in the official
+`Language Server Protocol specification
+<https://microsoft.github.io/language-server-protocol/specification>`__.
+
+We cautious about adding extensions. The most important considerations are:
+
+- **Editor support**: How many users will the feature be available to?
+- **Standardization**: Is the feature stable? Is it likely to be adopted by more
+  editors over time?
+- **Utility**: Does the feature provide a lot of value?
+- **Complexity**: Is this hard to implement in clangd, or constrain future work?
+  Is the protocol complicated?
+
+These extensions may evolve or disappear over time. If you use them, try to
+recover gracefully if the structures aren't what's expected.
+
+Switch between the implementation file and the header
+=====================================================
+
+*This extension is supported in clangd 6 and newer.*
+
+Switching between the implementation file and the header is an important
+feature for C++.  A language server that understands C++ can do a better job
+than the editor.
+
+**New client->server request**: ``textDocument/switchSourceHeader``.
+
+Lets editors switch between the main source file (``*.cpp``) and header (``*.h``).
+
+Parameter: ``TextDocumentIdentifier``: an open file.
+
+Result: ``string``: the URI of the corresponding header (if a source file was
+provided) or source file (if a header was provided).
+
+If the corresponding file can't be determined, ``""`` is returned.
+
+File status
+===========
+
+*This extension is supported in clangd 8 and newer.*
+
+It is important to provide feedback to the user when the UI is not responsive.
+
+This extension provides information about activity on clangd's per-file worker
+thread.  This information can be displayed to users to let them know that the
+language server is busy with something.  For example, in clangd, building the
+AST blocks many other operations.
+
+**New server->client notification**: ``textDocument/clangd.fileStatus``
+
+Sent when the current activity for a file changes. Replaces previous activity
+for that file.
+
+Parameter: ``FileStatus`` object with properties:
+
+- ``uri : string``: the document whose status is being updated.
+- ``state : string``: human-readable information about current activity.
+
+**New initialization option**: ``initializationOptions.clangdFileStatus : bool``
+
+Enables receiving ``textDocument/clangd.fileStatus`` notifications.
+
+Compilation commands
+====================
+
+*This extension is supported in clangd 8 and newer.*
+
+clangd relies on knowing accurate compilation options to correctly interpret a
+file. Typically they are found in a ``compile_commands.json`` file in a
+directory that contains the file, or an ancestor directory. The following
+extensions allow editors to supply the commands over LSP instead.
+
+**New initialization option**: ``initializationOptions.compilationDatabasePath : string``
+
+Specifies the directory containing the compilation database (e.g.,
+``compile_commands.json``). This path will be used for all files, instead of
+searching their ancestor directories.
+
+**New initialization option**: ``initializationOptions.fallbackFlags : string[]``
+
+Controls the flags used when no specific compile command is found.  The compile
+command will be approximately ``clang $FILE $fallbackFlags`` in this case.
+
+**New configuration setting**: ``settings.compilationDatabaseChanges : {string: CompileCommand}``
+
+Provides compile commands for files. This can also be provided on startup as
+``initializationOptions.compilationDatabaseChanges``.
+
+Keys are file paths (Not URIs!)
+
+Values are ``{workingDirectory: string, compilationCommand: string[]}``.
+
+Force diagnostics generation
+============================
+
+*This extension is supported in clangd 7 and newer.*
+
+Clangd does not regenerate diagnostics for every version of a file (e.g., after
+every keystroke), as that would be too slow. Its heuristics ensure:
+
+- diagnostics do not get too stale,
+- if you stop editing, diagnostics will catch up.
+
+This extension allows editors to force diagnostics to be generated or not
+generated at a particular revision.
+
+**New property of** ``textDocument/didChange`` **request**: ``wantDiagnostics : bool``
+
+- if true, diagnostics will be produced for exactly this version.
+- if false, diagnostics will not be produced for this version, even if there
+  are no further edits.
+- if unset, diagnostics will be produced for this version or some subsequent
+  one in a bounded amount of time.
+
+Diagnostic categories
+=====================
+
+*This extension is supported in clangd 8 and newer.*
+
+Clang compiler groups diagnostics into categories (e.g., "Inline Assembly
+Issue").  Clangd can emit these categories for interested editors.
+
+**New property of** ``Diagnostic`` **object**: ``category : string``:
+
+A human-readable name for a group of related diagnostics.  Diagnostics with the
+same code will always have the same category.
+
+**New client capability**: ``textDocument.publishDiagnostics.categorySupport``:
+
+Requests that clangd send ``Diagnostic.category``.
+
+Inline fixes for diagnostics
+============================
+
+*This extension is supported in clangd 8 and newer.*
+
+LSP specifies that code actions for diagnostics (fixes) are retrieved
+asynchronously using ``textDocument/codeAction``. clangd always computes fixes
+eagerly.  Providing them alongside diagnostics can improve the UX in editors.
+
+**New property of** ``Diagnostic`` **object**: ``codeActions : CodeAction[]``:
+
+All the code actions that address this diagnostic.
+
+**New client capability**: ``textDocument.publishDiagnostics.codeActionsInline : bool``
+
+Requests clangd to send ``Diagnostic.codeActions``.
+
+Symbol info request
+===================
+
+*This extension is supported in clangd 8 and newer.*
+
+**New client->server request**: ``textDocument/symbolInfo``:
+
+This request attempts to resolve the symbol under the cursor, without
+retrieving further information (like definition location, which may require
+consulting an index).  This request was added to support integration with
+indexes outside clangd.
+
+Parameter: ``TextDocumentPositionParams``
+
+Response: ``SymbolDetails``, an object with properties:
+
+- ``name : string`` the unqualified name of the symbol
+- ``containerName : string`` the enclosing namespace, class etc (without
+  trailing ``::``)
+- ``usr : string``: the clang-specific "unified symbol resolution" identifier
+- ``id : string?``: the clangd-specific opaque symbol ID

clang-tools-extra/trunk/docs/clangd/Features.rst

+========
+Features
+========
+
+.. role:: raw-html(raw)
+   :format: html
+
+Here is what clangd can do for you.  Screenshots below show `VSCode
+<https://code.visualstudio.com/>`__; the available features and UI depend on
+the editor.
+
+Errors and warnings
+===================
+
+clangd runs the clang compiler on your code as you type, and shows errors and
+warnings in-place.  Some errors are suppressed: diagnostics that require
+expanding templates in headers are disabled for performance reasons.
+
+:raw-html:`<details><summary markdown="span">Screenshot</summary>`
+
+.. image:: ErrorsInVSCode.png
+   :align: center
+   :alt: Demonstration of errors
+
+:raw-html:`</details>`
+
+Fixes in errors and warnings
+----------------------------
+
+The compiler can suggest fixes for many common problems automatically, and
+clangd can update the code for you.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: ApplyFixInVSCode.gif
+   :align: center
+   :alt: Applying a fix suggested by the compiler
+
+:raw-html:`</details>`
+
+Code completion
+===============
+
+You'll see suggestions as you type based on what methods, variables, etc are
+available in this context.
+
+:raw-html:`<details><summary markdown="span">Screenshot</summary>`
+
+.. image:: CodeCompletionInVSCode.png
+   :align: center
+   :alt: Code completion demonstration
+
+:raw-html:`</details>`
+
+Abbreviating words may help you find the right result faster. If you type in
+``camelCase`` but the function you're looking for is ``snake_case``, that's OK.
+
+Insertion of namespace qualifiers and includes
+----------------------------------------------
+
+**(New in v8)**
+clangd will sometimes suggest results from other files and namespaces. In this
+case the correct qualifier and ``#include`` directive will be inserted.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: CodeCompletionInsertsNamespaceQualifiersInVSCode.gif
+   :align: center
+   :alt: Code completion inserts namespace qualifiers
+
+:raw-html:`</details>`
+
+Signature help
+--------------
+
+Some editors will show you the parameters of the function you're calling, as
+you fill them in.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: SignatureHelpInVSCode.gif
+   :align: center
+   :alt: Demonstration of the signature help feature
+
+:raw-html:`</details>`
+
+Cross-references
+================
+
+The following features let you navigate your codebase.
+
+If there is no project-wide index, cross-references work across the files
+you have opened.
+
+Find definition/declaration
+---------------------------
+
+Jump to the definition or declaration of a symbol under the cursor.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: GoToDefinitionInVSCode.gif
+   :align: center
+   :alt: Demonstration of the "Go to definition" feature
+
+:raw-html:`</details>`
+
+Find references
+---------------
+
+Show all references to a symbol under the cursor.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: FindAllReferencesInVSCode.gif
+   :align: center
+   :alt: Demonstration of the "Find all references" feature
+
+:raw-html:`</details>`
+
+Some editors will automatically highlight local references to the selected
+symbol as you move around a file.
+
+Navigation
+==========
+
+clangd informs the editor of the code structure in the current file.
+Some editors use this to present an outline view:
+
+:raw-html:`<details><summary markdown="span">Screenshot</summary>`
+
+.. image:: OutlineInVSCode.png
+   :align: center
+   :alt: Outline of a file
+
+:raw-html:`</details>`
+
+In VSCode, the outline is also presented as breadcrumbs that allow jumping to a
+symbol within the current file.  Searching for symbols within the scope of the
+whole project is also possible.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: NavigationWithBreadcrumbsInVSCode.gif
+   :align: center
+   :alt: Navigation with breadcrumbs
+
+:raw-html:`</details>`
+
+Formatting
+==========
+
+clangd embeds `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`__,
+which can reformat your code: fixing indentation, breaking lines, and reflowing
+comments.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: FormatSelectionInVSCode.gif
+   :align: center
+   :alt: Formatting selected code
+
+:raw-html:`</details>`
+
+clangd respects your project's ``.clang-format`` file which controls styling
+options.
+
+Format-as-you-type is experimental and doesn't work well yet.
+
+Complete list of features
+=========================
+
+Here is a list of features that could be useful for editors, together with the
+implementation status in clangd, and specification in the Language Server
+Protocol.
+
+It is not clear whether or not some of the features mentioned below should be a
+part of the Language Server Protocol; those features might be eventually
+developed outside clangd or become clangd extensions to LSP.
+
++-------------------------------------+------------+----------+
+| C/C++ Editor feature                |  LSP       |  Clangd  |
++=====================================+============+==========+
+| Formatting                          | Yes        |   Yes    |
++-------------------------------------+------------+----------+
+| Completion                          | Yes        |   Yes    |
++-------------------------------------+------------+----------+
+| Diagnostics                         | Yes        |   Yes    |
++-------------------------------------+------------+----------+
+| Fix-its                             | Yes        |   Yes    |
++-------------------------------------+------------+----------+
+| Go to Definition                    | Yes        |   Yes    |
++-------------------------------------+------------+----------+
+| Signature Help                      | Yes        |   Yes    |
++-------------------------------------+------------+----------+
+| Document Highlights                 | Yes        |   Yes    |
++-------------------------------------+------------+----------+
+| Rename                              | Yes        |   Yes    |
++-------------------------------------+------------+----------+
+| Source hover                        | Yes        |   Yes    |
++-------------------------------------+------------+----------+
+| Find References                     | Yes        |   Yes    |
++-------------------------------------+------------+----------+
+| Document Symbols                    | Yes        |   Yes    |
++-------------------------------------+------------+----------+
+| Workspace Symbols                   | Yes        |   Yes    |
++-------------------------------------+------------+----------+
+| Code Lens                           | Yes        |   No     |
++-------------------------------------+------------+----------+
+| Code folding                        | Yes        |   No     |
++-------------------------------------+------------+----------+
+| Extract Local Variable              | Yes        |   No     |
++-------------------------------------+------------+----------+
+| Extract Function/Method             | Yes        |   No     |
++-------------------------------------+------------+----------+
+| Quick Assist                        | Yes        |   No     |
++-------------------------------------+------------+----------+
+| Hide Method                         | Yes        |   No     |
++-------------------------------------+------------+----------+
+| Implement Method                    | Yes        |   No     |
++-------------------------------------+------------+----------+
+| Gen. Getters/Setters                | Yes        |   No     |
++-------------------------------------+------------+----------+
+| Syntax and Semantic Coloring        | No         |   No     |
++-------------------------------------+------------+----------+
+| Call hierarchy                      | No         |   No     |
++-------------------------------------+------------+----------+
+| Type hierarchy                      | No         |   No     |
++-------------------------------------+------------+----------+
+| Organize Includes                   | No         |   No     |
++-------------------------------------+------------+----------+

clang-tools-extra/trunk/docs/clangd/Installation.rst

+===========================
+Getting started with clangd
+===========================
+
+.. role:: raw-html(raw)
+   :format: html
+
+To use clangd, you need to:
+
+- install clangd,
+- install a plugin for your editor,
+- tell clangd how your project is built.
+
+Installing clangd
+=================
+
+You need a **recent** version of clangd: 7.0 was the first usable release, and
+8.0 is much better.
+
+After installing, ``clangd --version`` should print ``clangd version 7.0.0`` or
+later.
+
+:raw-html:`<details><summary markdown="span">macOS</summary>`
+
+`Homebrew <https://brew.sh>`__ can install clangd along with LLVM:
+
+.. code-block:: console
+
+  $ brew install llvm
+
+If you don't want to use Homebrew, you can download the a binary release of
+LLVM from `releases.llvm.org <http://releases.llvm.org/download.html>`__.
+Alongside ``bin/clangd`` you will need at least ``lib/clang/*/include``:
+
+.. code-block:: console
+
+  $ cp clang+llvm-7.0.0/bin/clangd /usr/local/bin/clangd
+  $ cp -r clang+llvm-7.0.0/lib/clang/ /usr/local/lib/
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Windows</summary>`
+
+Download and run the LLVM installer from `releases.llvm.org
+<http://releases.llvm.org/download.html>`__.
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Debian/Ubuntu</summary>`
+
+The ``clang-tools`` package usually contains an old version of clangd.
+
+Try to install the latest release (8.0):
+
+.. code-block:: console
+
+  $ sudo apt-get install clang-tools-8
+
+If that is not found, at least ``clang-tools-7`` should be available.
+
+The ``clangd`` executable will be installed as ``/usr/bin/clangd-8``. Make it
+the default ``clangd``:
+
+.. code-block:: console
+
+  $ sudo update-alternatives --install /usr/bin/clangd clangd /usr/bin/clangd-8 100
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Other systems</summary>`
+
+Most distributions include clangd in a ``clang-tools`` package, or in the full
+``llvm`` distribution.
+
+For some platforms, binaries are also avaliable at `releases.llvm.org
+<http://releases.llvm.org/download.html>`__.
+
+:raw-html:`</details>`
+
+Editor plugins
+==============
+
+Language Server plugins are available for many editors. In principle, clangd
+should work with any of them, though the feature set and UI may vary.
+
+Here are some plugins we know work well with clangd.
+
+:raw-html:`<details><summary markdown="span">YouCompleteMe for Vim</summary>`
+
+`YouCompleteMe <https://valloric.github.io/YouCompleteMe/>`__ supports clangd.
+However, clangd support is not turned on by default, so you must install
+YouCompleteMe with ``install.py --clangd-completer``.
+
+We recommend changing a couple of YCM's default settings. In ``.vimrc`` add:
+
+::
+
+  " Let clangd fully control code completion
+  let g:ycm_clangd_uses_ycmd_caching = 0
+  " Use installed clangd, not YCM-bundled clangd which doesn't get updates.
+  let g:ycm_clangd_binary_path = exepath("clangd")
+
+You should see errors highlighted and code completions as you type.
+
+.. image:: CodeCompletionInYCM.png
+   :align: center
+   :alt: Code completion in YouCompleteMe
+
+YouCompleteMe supports many of clangd's features:
+
+- code completion,
+- diagnostics and fixes (``:YcmCompleter FixIt``),
+- find declarations, references, and definitions (``:YcmCompleter GoTo`` etc),
+- rename symbol (``:YcmCompleter RefactorRename``).
+
+**Under the hood**
+
+- **Debug logs**: run ``:YcmDebugInfo`` to see clangd status, and ``:YcmToggleLogs``
+  to view clangd's debug logs.
+- **Command-line flags**: Set ``g:ycm_clangd_args`` in ``.vimrc``, e.g.:
+
+  ::
+
+    let g:ycm_clangd_args = ['-log=verbose', '-pretty']
+
+- **Alternate clangd binary**: set ``g:ycm_clangd_binary_path`` in ``.vimrc``.
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">LanguageClient for Vim and Neovim</summary>`
+
+`LanguageClient-neovim <https://github.com/autozimu/LanguageClient-neovim>`__
+has `instructions for using clangd
+<https://github.com/autozimu/LanguageClient-neovim/wiki/Clangd>`__, and **may**
+be easier to install than YouCompleteMe.
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Eglot for Emacs</summary>`
+
+`eglot <https://github.com/joaotavora/eglot>`__ can be configured to work with
+clangd.
+
+Install eglot with ``M-x package-install RET eglot RET``.
+
+Add the following to ``~/.emacs`` to enable clangd:
+
+::
+
+  (require 'eglot)
+  (add-to-list 'eglot-server-programs '((c++-mode c-mode) "clangd"))
+  (add-hook 'c-mode-hook 'eglot-ensure)
+  (add-hook 'c++-mode-hook 'eglot-ensure)
+
+After restarting you should see diagnostics for errors in your code, and ``M-x
+completion-at-point`` should work.
+
+.. image:: DiagnosticsInEmacsEglot.png
+   :align: center
+   :alt: Diagnostics in Emacs
+
+eglot supports many of clangd's features, with caveats:
+
+- code completion, though the interaction is quite poor (even with
+  ``company-mode``, see below),
+- diagnostics and fixes,
+- find definitions and references (``M-x xref-find-definitions`` etc),
+- hover and highlights,
+- code actions (``M-x eglot-code-actions``).
+
+**company-mode**
+
+eglot does have basic integration with company-mode, which provides a more
+fluent completion UI.
+
+You can install it with ``M-x package-install RET company RET``, and enable it
+with ``M-x company-mode``.
+
+**company-clang is enabled by default**, and will interfere with clangd.
+Disable it in ``M-x customize-variable RET company-backends RET``.
+
+Completion still has some major limitations:
+
+- completions are alphabetically sorted, not ranked.
+- only pure-prefix completions are shown - no fuzzy matches.
+- completion triggering seems to be a bit hit-and-miss.
+
+.. image:: CodeCompletionInEmacsCompanyMode.png
+   :align: center
+   :alt: Completion in company-mode
+
+**Under the hood**
+
+- **Debug logs**: available in the ``EGLOT stderr`` buffer.
+- **Command-line flags and alternate binary**: instead of adding ``"clangd"``
+  to ``eglot-server-programs``, add ``("/path/to/clangd" "-log=verbose")`` etc.
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Visual Studio Code</summary>`
+
+The official extension is `vscode-clangd
+<https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`__
+and can be installed from within VSCode.
+
+Choose **View** --> **Extensions**, then search for "clangd". (Make sure the
+Microsoft C/C++ extension is **not** installed).
+
+After restarting, you should see red underlines underneath errors, and you
+should get rich code completions including e.g. function parameters.
+
+.. image:: CodeCompletionInVSCode.png
+   :align: center
+   :alt: Code completion in VSCode
+
+vscode-clangd has excellent support for all clangd features, including:
+
+- code completion
+- diagnostics and fixes
+- find declarations, references, and definitions
+- find symbol in file (``Ctrl-P @foo``) or workspace (``Ctrl-P #foo``)
+- hover and highlights
+- code actions
+
+**Under the hood**
+
+- **Debug logs**: when clangd is running, you should see "Clang Language
+  Server" in the dropdown of the Output panel (**View** -> **Output**).
+
+- **Command-line flags**: these can be passed in the ``clangd.arguments`` array
+  in your ``settings.json``. (**File** -> **Preferences** -> **Settings**).
+
+- **Alternate clangd binary**: set the ``clangd.path`` string in
+  ``settings.json``.
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Sublime Text</summary>`
+
+`tomv564/LSP <https://github.com/tomv564/LSP>`__ works with clangd out of the box.
+
+Select **Tools** --> **Install Package Control** (if you haven't installed it
+yet).
+
+Press ``Ctrl-Shift-P`` and select **Package Control: Install Package**. Select
+**LSP**.
+
+Press ``Ctrl-Shift-P`` and select **LSP: Enable Language Server Globally**.
+Select **clangd**.
+
+Open a C++ file, and you should see diagnostics and completion:
+
+.. image:: CodeCompletionInSublimeText.png
+   :align: center
+   :alt: Code completion in Sublime Text
+
+
+The LSP package has excellent support for all most clangd features, including:
+
+- code completion (a bit noisy due to how snippets are presented)
+- diagnostics and fixes
+- find definition and references
+- hover and highlights
+- code actions
+
+**Under the hood**
+
+Settings can be tweaked under **Preferences** --> **Package Settings** -->
+**LSP**.
+
+- **Debug logs**: add ``"log_stderr": true``
+- **Command-line flags and alternate clangd binary**: inside the ``"clients":
+  {"clangd": { ... } }`` section, add ``"command": ["/path/to/clangd",
+  "-log=verbose"]`` etc.
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Other editors</summary>`
+
+There is a directory of LSP clients at `langserver.org
+<http://langserver.org>`__.
+
+A generic client should be configured to run the command ``clangd``, and
+communicate via the language server protocol on standard input/output.
+
+If you don't have strong feelings about an editor, we suggest you try out
+`VSCode <https://code.visualstudio.com/>`__, it has excellent language server
+support and most faithfully demonstrates what clangd can do.
+
+:raw-html:`</details>`
+
+Project setup
+=============
+
+To understand source code in your project, clangd needs to know the build
+flags.  (This is just a fact of life in C++, source files are not
+self-contained.)
+
+By default, clangd will assume that source code is built as ``clang
+some_file.cc``, and you'll probably get spurious errors about missing
+``#include``\ d files, etc.  There are a couple of ways to fix this.
+
+``compile_commands.json``
+-------------------------
+
+``compile_commands.json`` file provides compile commands for all source files
+in the project.  This file is usually generated by the build system, or tools
+integrated with the build system.  Clangd will look for this file in the parent
+directories of the files you edit.
+
+:raw-html:`<details><summary markdown="span">CMake-based projects</summary>`
+
+If your project builds with CMake, it can generate ``compile_commands.json``.
+You should enable it with:
+
+::
+
+  $ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1
+
+``compile_commands.json`` will be written to your build directory.  You should
+symlink it (or copy it) to the root of your source tree, if they are different.
+
+::
+
+  $ ln -s ~/myproject/compile_commands.json ~/myproject-build/
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Other build systems, using Bear</summary>`
+
+`Bear <https://github.com/rizsotto/Bear>`__ is a tool that generates a
+``compile_commands.json`` file by recording a complete build.
+
+For a ``make``-based build, you can run ``make clean; bear make`` to generate the
+file (and run a clean build!)
+
+:raw-html:`</details>`
+
+Other tools can also generate this file. See `the compile_commands.json
+specification <https://clang.llvm.org/docs/JSONCompilationDatabase.html>`__.
+
+``compile_flags.txt``
+---------------------
+
+If all files in a project use the same build flags, you can put those flags,
+one flag per line, in ``compile_flags.txt`` in your source root.
+
+Clangd will assume the compile command is ``clang $FLAGS some_file.cc``.
+
+Creating this file by hand is a reasonable place to start if your project is
+quite simple.
+
+Project-wide Index
+==================
+
+By default clangd only has a view on symbols coming from files you are
+currently editing. You can extend this view to whole project by providing a
+project-wide index to clangd.  There are two ways to do this.
+
+- Pass an experimental `-background-index` command line argument.  With
+  this feature enabled, clangd incrementally builds an index of projects
+  that you work on and uses the just-built index automatically.
+
+- Generate an index file using `clangd-indexer
+  <https://github.com/llvm/llvm-project/blob/master/clang-tools-extra/clangd/indexer/IndexerMain.cpp>`__
+  Then you can pass generated index file to clangd using
+  `-index-file=/path/to/index_file`.  *Note that clangd-indexer isn't
+  included alongside clangd in the Debian clang-tools package. You will
+  likely have to build clangd from source to use this option.*

clang-tools-extra/trunk/docs/clangd/index.rst

-============
-Clangd
-============
-
-.. contents::
+======
+clangd
+======
 
 .. toctree::
    :maxdepth: 1
 
-:program:`Clangd` is an implementation of the `Language Server Protocol
-<https://github.com/Microsoft/language-server-protocol>`_ leveraging Clang.
-Clangd's goal is to provide language "smartness" features like code completion,
-find references, etc. for clients such as C/C++ Editors.
-
-Using Clangd
-==================
-
-:program:`Clangd` is not meant to be used by C/C++ developers directly but
-rather from a client implementing the protocol. A client would be typically
-implemented in an IDE or an editor.
-
-At the moment, `Visual Studio Code <https://code.visualstudio.com/>`_ is mainly
-used in order to test :program:`Clangd` but more clients are likely to make
-use of :program:`Clangd` in the future as it matures and becomes a production
-quality tool. If you are interested in trying :program:`Clangd` in combination
-with Visual Studio Code, you can start by `installing Clangd`_ or
-`building Clangd`_, then open Visual Studio Code in the clangd-vscode folder and
-launch the extension.
-
-Installing Clangd
-==================
-
-Packages are available for debian-based distributions, see the `LLVM packages
-page <https://apt.llvm.org/>`_. :program:`Clangd` is included in the
-`clang-tools` package.
-However, it is a good idea to check your distribution's packaging system first
-as it might already be available.
-
-Otherwise, you can install :program:`Clangd` by `building Clangd`_ first.
-
-Building Clangd
-==================
-
-You can follow the instructions for `building Clang
-<https://clang.llvm.org/get_started.html>`_ but "extra Clang tools" is **not**
-optional.
-
-Current Status
-==================
-
-Many features could be implemented in :program:`Clangd`.
-Here is a list of features that could be useful with the status of whether or
-not they are already implemented in :program:`Clangd` and specified in the
-Language Server Protocol. Note that for some of the features, it is not clear
-whether or not they should be part of the Language Server Protocol, so those
-features might be eventually developed outside :program:`Clangd` or as an
-extension to the protocol.
-
-+-------------------------------------+------------+----------+
-| C/C++ Editor feature                |  LSP       |  Clangd  |
-+=====================================+============+==========+
-| Formatting                          | Yes        |   Yes    |
-+-------------------------------------+------------+----------+
-| Completion                          | Yes        |   Yes    |
-+-------------------------------------+------------+----------+
-| Diagnostics                         | Yes        |   Yes    |
-+-------------------------------------+------------+----------+
-| Fix-its                             | Yes        |   Yes    |
-+-------------------------------------+------------+----------+
-| Go to Definition                    | Yes        |   Yes    |
-+-------------------------------------+------------+----------+
-| Signature Help                      | Yes        |   Yes    |
-+-------------------------------------+------------+----------+
-| Document Highlights                 | Yes        |   Yes    |
-+-------------------------------------+------------+----------+
-| Rename                              | Yes        |   Yes    |
-+-------------------------------------+------------+----------+
-| Source hover                        | Yes        |   Yes    |
-+-------------------------------------+------------+----------+
-| Find References                     | Yes        |   Yes    |
-+-------------------------------------+------------+----------+
-| Document Symbols                    | Yes        |   Yes    |
-+-------------------------------------+------------+----------+
-| Workspace Symbols                   | Yes        |   Yes    |
-+-------------------------------------+------------+----------+
-| Code Lens                           | Yes        |   No     |
-+-------------------------------------+------------+----------+
-| Code folding                        | Yes        |   No     |
-+-------------------------------------+------------+----------+
-| Extract Local Variable              | Yes        |   No     |
-+-------------------------------------+------------+----------+
-| Extract Function/Method             | Yes        |   No     |
-+-------------------------------------+------------+----------+
-| Quick Assist                        | Yes        |   No     |
-+-------------------------------------+------------+----------+
-| Hide Method                         | Yes        |   No     |
-+-------------------------------------+------------+----------+
-| Implement Method                    | Yes        |   No     |
-+-------------------------------------+------------+----------+
-| Gen. Getters/Setters                | Yes        |   No     |
-+-------------------------------------+------------+----------+
-| Syntax and Semantic Coloring        | No         |   No     |
-+-------------------------------------+------------+----------+
-| Call hierarchy                      | No         |   No     |
-+-------------------------------------+------------+----------+
-| Type hierarchy                      | No         |   No     |
-+-------------------------------------+------------+----------+
-| Organize Includes                   | No         |   No     |
-+-------------------------------------+------------+----------+
-
-Editor Integration
-==================
-
-Any full-featured Language Server Protocol Client implementation should work
-with :program:`Clangd`. This `list
-<https://langserver.org/#implementations-client>`_ contains information about
-extensions and plugins that are known to work for different editors.
-
-Vim Integration
----------------
-
-LanguageClient-neovim
-~~~~~~~~~~~~~~~~~~~~~
-
-One of the options of using :program:`Clangd` in :program:`vim` (or
-:program:`nvim`) is to utilize `LanguageClient-neovim
-<https://github.com/autozimu/LanguageClient-neovim>`_ plugin. Please see the
-`Clangd Wiki page
-<https://github.com/autozimu/LanguageClient-neovim/wiki/Clangd>`_ for
-instructions.
-
-VSCode Integration
-------------------
-
-:program:`VSCode` provides `vscode-clangd
-<https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`_
-which is published in Visual Studio Marketplace and can be installed direcetly
-from :program:`VSCode`.
-
-Emacs Integration
------------------
-
-:program:`Emacs` provides `lsp-mode <github.com/emacs-lsp/lsp-mode>`_ and
-`Eglot <https://github.com/joaotavora/eglot>`_ plugins for LSP integration.
-
-Project-wide Index
-==================
-
-By default :program:`Clangd` only has a view on symbols coming from files you
-are currently editing. You can extend this view to whole project by providing a
-project-wide index to :program:`Clangd`.
-
-There are two ways you can generate a project-wide index for clangd:
-
-- Passing experimental `-background-index` commandline argument, which will
-  incrementally build an index of projects that you work on and make use of that
-  in clangd automatically.
-- Generate an index file using `clangd-indexer
-  <https://github.com/llvm-mirror/clang-tools-extra/blob/master/clangd/indexer/IndexerMain.cpp>`_
-  Afterwards you can pass generated index file to clangd using
-  `-index-file=/path/to/index_file`.  *Note that clangd-indexer isn't included
-  alongside clangd in the standard clang-tools package. You will likely have to
-  build from source to use this option*
-
-Getting Involved
-==================
-
-A good place for interested contributors is the `Clangd developer mailing list
-<https://lists.llvm.org/mailman/listinfo/clangd-dev>`_. For discussions with the
-broader community on topics not only related to Clangd, use
-`Clang developer mailing list
-<https://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
-If you're also interested in contributing patches to :program:`Clangd`, take a
-look at the `LLVM Developer Policy
-<https://llvm.org/docs/DeveloperPolicy.html>`_ and `Code Reviews
-<https://llvm.org/docs/Phabricator.html>`_ page. Contributions of new features
-to the `Language Server Protocol
-<https://github.com/Microsoft/language-server-protocol>`_ itself would also be
-very useful, so that :program:`Clangd` can eventually implement them in a
-conforming way.
+   Installation
+   Features
+
+What is clangd?
+===============
+
+clangd understands your C++ code and adds smart features to your editor: code
+completion, compile errors, go-to-definition and more.
+
+clangd is a language server that implements the `Language Server Protocol
+<https://github.com/Microsoft/language-server-protocol>`__; it can work with
+many editors through a plugin.  Here's Visual Studio Code with the clangd
+plugin, demonstrating code completion:
+
+.. image:: CodeCompletionInVSCode.png
+   :align: center
+   :alt: Code completion in VSCode
+
+clangd is based on the `Clang <https://clang.llvm.org>`__ C++ compiler, and is
+part of the `LLVM <https://llvm.org>`__ project.

clang-tools-extra/trunk/docs/conf.py

 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
 #html_favicon = None
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 #html_use_smartypants = True

clang-tools-extra/trunk/docs/index.rst

.. toctree::
    :maxdepth: 2
 
    clang-tidy/index
    include-fixer
    modularize
    pp-trace
    clang-rename
    clangd/index
+   clangd/DeveloperDocumentation
    clang-doc
 
 
 Doxygen Documentation
 =====================
 The Doxygen documentation describes the **internal** software that makes up the
 tools of clang-tools-extra, not the **external** use of these tools. The Doxygen
 documentation contains no instructions about how to use the tools, only the APIs