From cdb7473d6c65bc397e9054e4673c781ae30637aa Mon Sep 17 00:00:00 2001 From: Alex Carney Date: Tue, 12 Sep 2023 23:23:25 +0100 Subject: [PATCH] code: First pass (of many) at rewriting the README --- code/README.md | 83 ++++---------------------------------------------- 1 file changed, 6 insertions(+), 77 deletions(-) diff --git a/code/README.md b/code/README.md index 3620f21f2..9e11566b6 100644 --- a/code/README.md +++ b/code/README.md @@ -2,36 +2,13 @@ The Esbonio extension integrates the [`esbonio`](https://pypi.org/project/esbonio/) language server into VSCode. -The `esbonio` language server aims to make it easier to work with [Sphinx](https://www.sphinx-doc.org/en/master/) documentation projects by providing completion suggestions for your cross references and many other features. - -## What about 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. - -**Wait.. so why does the Esbonio VSCode extension still exist?** - -The reStructuredText extension takes a more conservative approach to adopting new VSCode features and APIs leaving the Esbonio extension free to more aggressively follow new developments. -The Esbonio extension is developed alongside the language server itself, which allows for easy testing of new features without waiting for downstream projects to catch up. -Finally, the Esbonio extension serves as an up to date reference for projects that integrate `esbonio` into other editors. - -**That sounds great... but which extension is right for me?** - -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 - -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 +The `esbonio` language server aims to make it easier to work with [Sphinx](https://www.sphinx-doc.org/en/master/) documentation projects by bringing IDE-like features to your documentation. ## Features -### Preview +### Live Preview -The extension can show a HTML preview of the documentation +The extension can show a live HTML preview of the documentation ![HTML Preview](../resources/images/vscode-preview-demo.gif) @@ -71,55 +48,7 @@ Sections within a document are displayed in the "Outline" view ![Document Outline](../resources/images/document-symbols-demo.png) -### Syntax Highlighting - -Syntax Highlighting is provided thanks to the [reStructuredText Syntax Highlighting Extension](https://marketplace.visualstudio.com/items?itemName=trond-snekvik.simple-rst) extension. - -## Setup - -The language server works by wrapping an instance of Sphinx's application object, -inspecting it and exposing the results over the Language Service Protocol. As Sphinx is -a Python application this also dictates thats the Language Server is written in Python -and distributed as a package on [PyPi](https://pypi.org/project/esbonio/). - -In order to correctly wrap your Sphinx application this requires the Language Server be -installed into the same environment as the one that you use to build your -documentation. - -There are a number of ways this can be accomplished. - -### Automatically - -The extension does its best to automate the installation and application of updates to the -Language Server. By default Esbonio will use the Python environment you have configured -[Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) -when installing and running the server. If however, you don't have the Python extension -installed or you want to use a different Python environment for your documentation there -is a configuration option `esbonio.server.pythonPath` that you can use to configure the -environment. - -There are a number of configuration options that allow you to control exactly how -installation and updates are handled. See the -[documentation](https://swyddfa.github.io/esbonio/docs/lsp/editors/vscode.html#configuration) -for more details. - -![Setup Demo](../resources/images/vscode-setup-demo.gif) - -### Manually - -Alternatively you can opt to manage the installation of the language server entirely -yourself. To install the Lanaguage Server open the terminal in your desired Python -environment and run - -``` -(env) $ pip install esbonio -``` - -Then all you have to ensure is that Esbonio is configured to use the same environment, -either through the -[Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) -or through the `esbonio.server.pythonPath` configuration option. +## Alternatives -To also manage updates manually, be sure to look at the -[documentation](https://swyddfa.github.io/esbonio/docs/lsp/editors/vscode.html#configuration) -for options on how to disable automatic updates. +The [reStructuredText](https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext) extension as of [v171.0.0](https://github.com/vscode-restructuredtext/vscode-restructuredtext/releases/tag/171.0.0) 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 for working with reStructuredText in general.