Merge pull request #370 from swyddfa/develop

.pre-commit-config.yaml

@@ -2,7 +2,7 @@ exclude: '.bumpversion.cfg$'
 repos:
 
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.1.0
+  rev: v4.2.0
   hooks:
   - id: end-of-file-fixer
   - id: trailing-whitespace

README.md

@@ -9,6 +9,42 @@
 
 Esbonio aims to make it easier to work with [reStructuredText](https://docutils.sourceforge.io/rst.html) tools such as [Sphinx](https://www.sphinx-doc.org/en/master/) by providing a [Language Server](https://langserver.org/) to enhance your editing experience.
 The Esbonio project is made up from a number of sub-projects
+## `lib/esbonio/` - A Language Server for Sphinx projects.
+[![PyPI](https://img.shields.io/pypi/v/esbonio?style=flat-square)![PyPI - Downloads](https://img.shields.io/pypi/dm/esbonio?style=flat-square)](https://pypistats.org/packages/esbonio)[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/swyddfa/esbonio/blob/develop/lib/esbonio/LICENSE)
+
+The language server is still in early development, but already provides the following features.
+
+**Completion**
+
+<p align="center">
+  <img src="./resources/images/completion-demo.gif" alt="Completion Suggestions Demo"></img>
+</p>
+
+**Definitions**
+
+<p align="center">
+  <img src="./resources/images/definition-demo.gif" alt="Goto Definition Demo"></img>
+</p>
+
+**Diagnostics**
+
+<p align="center">
+  <img src="./resources/images/diagnostic-sphinx-errors-demo.png" alt="Diagnostics Demo"></img>
+</p>
+
+**Document Links**
+
+<p align="center">
+  <img src="./resources/images/document-links-demo.png" alt="Document Links Demo"></img>
+</p>
+
+
+**Document Symbols**
+
+<p align="center">
+  <img src="./resources/images/document-symbols-demo.png" alt="Document Symbols Demo"></img>
+</p>
+
 
 ## `code/` - A VSCode extension for editing Sphinx projects
 [![Visual Studio Marketplace Version](https://img.shields.io/visual-studio-marketplace/v/swyddfa.esbonio?style=flat-square)![Visual Studio Marketplace Installs](https://img.shields.io/visual-studio-marketplace/i/swyddfa.esbonio?style=flat-square)![Visual Studio Marketplace Downloads](https://img.shields.io/visual-studio-marketplace/d/swyddfa.esbonio?style=flat-square)](https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio)[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/swyddfa/esbonio/blob/develop/code/LICENSE)
@@ -17,9 +53,9 @@ The Esbonio project is made up from a number of sub-projects
    <img src="./resources/images/vscode-preview-demo.gif" alt="HTML Preview Demo"></img>
 </p>
 
-Most of the extension's functionality is provided through the `esbonio` language server (see below.)
+This extension is purely focused on bringing the `esbonio` language server into VSCode to help with development and testing new ideas.
 
-### What about the reStructuredText Extension?
+### You're probably looking for the reStructuredText Extension
 
 You may already be familiar with the [reStructuredText](https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext) extension which, as of [v171.0.0](https://github.com/vscode-restructuredtext/vscode-restructuredtext/releases/tag/171.0.0) now also integrates the `esbonio` language server into VSCode.
 It also integrates other tools such as the linters [`doc8`](https://pypi.org/project/doc8/) and [`rstcheck`](https://pypi.org/project/rstcheck/) and provides additional editor functionality making it easier to work with reStructuredText in general.
@@ -35,41 +71,12 @@ Finally, the Esbonio extension serves as an up to date reference for projects th
 Try the reStructuredText extension if
 
 - You need an extension compatible with older versions of VSCode
-- You are interested in additional features beyond what is provided by the language server
+- You are looking for a more rounded editing experience.
 
 Try the Esbonio extension if
 
 - You want to make use of the newer features available in recent VSCode versions
 - You are only interested in the features provided by the language server
 
-## `lib/esbonio/` - A Language Server for Sphinx projects.
-[![PyPI](https://img.shields.io/pypi/v/esbonio?style=flat-square)![PyPI - Downloads](https://img.shields.io/pypi/dm/esbonio?style=flat-square)](https://pypistats.org/packages/esbonio)[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/swyddfa/esbonio/blob/develop/lib/esbonio/LICENSE)
-
-The language server is still in early development, but already provides the following features.
-
-**Completion**
-
-<p align="center">
-  <img src="./resources/images/completion-demo.gif" alt="Completion Suggestions Demo"></img>
-</p>
-
-**Definitions**
-
-<p align="center">
-  <img src="./resources/images/definition-demo.gif" alt="Goto Definition Demo"></img>
-</p>
-
-**Diagnostics**
-
-<p align="center">
-  <img src="./resources/images/diagnostic-sphinx-errors-demo.png" alt="Diagnostics Demo"></img>
-</p>
-
-**Document Symbols**
-
-<p align="center">
-  <img src="./resources/images/document-symbols-demo.png" alt="Document Symbols Demo"></img>
-</p>
-
 ## `lib/esbonio-extensions/` - A collection of Sphinx extensions
 [![PyPI](https://img.shields.io/pypi/v/esbonio-extensions?style=flat-square)![PyPI - Downloads](https://img.shields.io/pypi/dm/esbonio-extensions?style=flat-square)](https://pypistats.org/packages/esbonio-extensions)[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/swyddfa/esbonio/blob/develop/lib/esbonio-extensions/LICENSE)

code/changes/358.enhancement.rst

@@ -0,0 +1 @@
+Added the ``esbonio.sphinx.forceFullBuild`` option (default: ``true``) which can be used to control if the language server forces a full Sphinx build on startup.

code/changes/359.enhancement.rst

@@ -0,0 +1 @@
+Added the ``esbonio.sphinx.numJobs`` option (default: ``auto``) which can be used to control the number of parallel jobs used by Sphinx.

code/package.json

@@ -250,6 +250,18 @@
                         "default": null,
                         "description": "The Language Server should be able to automatically find the folder containing your project's 'conf.py' file. However this setting can be used to force the Language Server to use a particular directory if required."
                     },
+                    "esbonio.sphinx.forceFullBuild": {
+                        "scope": "window",
+                        "type": "boolean",
+                        "default": true,
+                        "description": "By default the language server will force a full build of your documentation on startup to help improve the accuracy of some features like diagnostics. Disabling this option can help improve startup time for larger projects at the expense of certain features being less accurate."
+                    },
+                    "esbonio.sphinx.numJobs": {
+                        "scope": "window",
+                        "type": "integer",
+                        "default": 0,
+                        "markdownDescription": "The number of parallel jobs to use during a Sphinx build.\n\n- A value of `0` is equivalent to passing `-j auto` to a `sphinx-build` command.\n- A value of `1` will disable parallel processing."
+                    },
                     "esbonio.sphinx.srcDir": {
                         "scope": "window",
                         "type": "string",

code/src/constants.ts

@@ -3,7 +3,7 @@ export const PYTHON_EXTENSION = "ms-python.python"
 
 export namespace Server {
   export const REQUIRED_PYTHON = "3.6.0"
-  export const REQUIRED_VERSION = "0.10.2"
+  export const REQUIRED_VERSION = "0.11.0"
 }
 
 export namespace Commands {

code/src/lsp/client.ts

@@ -19,30 +19,39 @@ const DEBUG = process.env.VSCODE_LSP_DEBUG === "true"
 export interface SphinxConfig {
 
   /**
-   * Sphinx's version number.
+   * The directory where Sphinx's build output should be stored.
    */
-  version?: string
+  buildDir?: string
+
+  /**
+   * The name of the builder to use.
+   */
+  builderName?: string
 
   /**
    * The directory containing the project's 'conf.py' file.
    */
   confDir?: string
 
   /**
-   * The source dir containing the *.rst files for the project.
+   * Flag to force a full build of the documentation on startup.
    */
-  srcDir?: string
+  forceFullBuild?: boolean
 
   /**
-   * The directory where Sphinx's build output should be stored.
+   * The number of parallel jobs to use
    */
-  buildDir?: string
+  numJobs?: number | string
 
   /**
-   * The name of the builder to use.
+   * The source dir containing the *.rst files for the project.
    */
-  builderName?: string
+  srcDir?: string
 
+  /**
+   * Sphinx's version number.
+   */
+  version?: string
 }
 
 /**
@@ -285,18 +294,22 @@ export class EsbonioClient {
    */
   private getLanguageClientOptions(config: vscode.WorkspaceConfiguration): LanguageClientOptions {
 
-    let cache = this.context.storageUri.path
 
     let buildDir = config.get<string>('sphinx.buildDir')
+    let numJobs = config.get<number>('sphinx.numJobs')
+
     if (!buildDir) {
+      let cache = this.context.storageUri.path
       buildDir = join(cache, 'sphinx')
     }
 
     let initOptions: InitOptions = {
       sphinx: {
-        srcDir: config.get<string>("sphinx.srcDir"),
+        buildDir: buildDir,
         confDir: config.get<string>('sphinx.confDir'),
-        buildDir: buildDir
+        forceFullBuild: config.get<boolean>('sphinx.forceFullBuild'),
+        numJobs: numJobs === 0 ? 'auto' : numJobs,
+        srcDir: config.get<string>("sphinx.srcDir"),
       },
       server: {
         logLevel: config.get<string>('server.logLevel'),

docs/index.rst

@@ -41,6 +41,14 @@ Here is a quick summary of the features implemented by the language server.
          :align: center
          :target: /_images/diagnostic-sphinx-errors-demo.png
 
+   .. collection-item:: Document Links
+
+      The language server implements :lsp:`textDocument/documentLink` to make references to other files "Ctrl + Clickable"
+
+      .. figure:: ../resources/images/document-links-demo.png
+         :align: center
+         :target: /_images/document-links-demo.png
+
    .. collection-item:: Document Symbols
 
       The language server implements :lsp:`textDocument/documentSymbol` which

docs/lsp/api-reference.rst

@@ -11,24 +11,38 @@ Language Servers
 
 .. autofunction:: esbonio.lsp.create_language_server
 
+RstLanguageServer
+^^^^^^^^^^^^^^^^^
+
 .. autoclass:: esbonio.lsp.rst.RstLanguageServer
    :members:
    :show-inheritance:
 
+SphinxLanguageServer
+^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: esbonio.lsp.sphinx.SphinxConfig
+   :members:
+
 .. autoclass:: esbonio.lsp.sphinx.SphinxLanguageServer
    :members:
    :show-inheritance:
 
+.. autoclass:: esbonio.lsp.sphinx.MissingConfigError
+
 Language Features
 -----------------
 
-.. autoclass:: esbonio.lsp.rst.LanguageFeature
+.. autoclass:: esbonio.lsp.LanguageFeature
+   :members:
+
+.. autoclass:: esbonio.lsp.CompletionContext
    :members:
 
-.. autoclass:: esbonio.lsp.rst.CompletionContext
+.. autoclass:: esbonio.lsp.DefinitionContext
    :members:
 
-.. autoclass:: esbonio.lsp.rst.DefinitionContext
+.. autoclass:: esbonio.lsp.DocumentLinkContext
    :members:
 
 Directives
@@ -45,8 +59,14 @@ Directives
 .. autoclass:: ArgumentCompletion
    :members:
 
+.. autoclass:: ArgumentDefinition
+   :members:
+
+.. autoclass:: ArgumentLink
+   :members:
+
 .. autoclass:: Directives
-   :members: add_argument_completion_provider, add_documentation
+   :members: add_argument_completion_provider, add_argument_definition_provider, add_argument_link_provider, add_documentation
 
 Roles
 ^^^^^
@@ -60,14 +80,17 @@ Roles
    :annotation: = re.compile(...)
 
 .. autoclass:: Roles
-   :members: add_documentation, add_target_definition_provider, add_target_completion_provider
+   :members: add_documentation, add_target_definition_provider, add_target_completion_provider, add_target_link_provider
 
 .. autoclass:: TargetCompletion
    :members:
 
 .. autoclass:: TargetDefinition
    :members:
 
+.. autoclass:: TargetLink
+   :members:
+
 Testing
 -------
 

docs/lsp/extending.rst

@@ -32,7 +32,7 @@ Architecture
 
    Language Feature
       Language features are subclasses of :class:`~esbonio.lsp.rst.LanguageFeature`.
-      They are typically based on a single aspect of reStructuedText (e.g. :class:`~esbonio.lsp.roles.Roles`) or Sphinx (e.g. :class:``  responsible for providing
+      They are typically based on a single aspect of reStructuredText (e.g. :class:`~esbonio.lsp.roles.Roles`) or Sphinx (e.g. :class:``  responsible for providing
 
       Language Features (where it makes sense) should be server agnostic, that way the same features can be reused across different envrionments.