diff --git a/docs/.vscode/settings.json b/docs/.vscode/settings.json new file mode 100644 index 000000000..d95755e28 --- /dev/null +++ b/docs/.vscode/settings.json @@ -0,0 +1,11 @@ +{ + "esbonio.sphinx.buildCommand": [ + "sphinx-build", + "-M", + "html", + ".", + "./_build" + ], + "esbonio.sphinx.enableDevTools": false, + "esbonio.trace.server": "verbose" +} diff --git a/docs/images/preview-architecture.svg b/docs/images/preview-architecture.svg new file mode 100644 index 000000000..4c30cff7e --- /dev/null +++ b/docs/images/preview-architecture.svg @@ -0,0 +1,17 @@ + + + + + + + + 12345678http://...ws://...HTTP ServerWebSocketServerLanguage ServerLSP Protocol"Preview" Protocol \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index fbc6f7408..4b8d55d11 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -93,6 +93,7 @@ Here is a quick summary of the features implemented by the language server. lsp/configuration lsp/advanced-usage lsp/extending + lsp/reference changelog Sphinx Extensions diff --git a/docs/lsp/reference.rst b/docs/lsp/reference.rst new file mode 100644 index 000000000..3e9b42173 --- /dev/null +++ b/docs/lsp/reference.rst @@ -0,0 +1,8 @@ +Reference +========= + +.. toctree:: + :glob: + :maxdepth: 2 + + reference/* diff --git a/docs/lsp/reference/previews.rst b/docs/lsp/reference/previews.rst new file mode 100644 index 000000000..83d8b0fd9 --- /dev/null +++ b/docs/lsp/reference/previews.rst @@ -0,0 +1,33 @@ +Preview Implementation +====================== + +This page gives an overview of how the preview feature in ``esbonio`` is implemented. + + +.. figure:: /images/preview-architecture.svg + :align: center + + Architecture of the preview feature + +The diagram above shows the main components involved in implementing the preview feature. + +- On the left we have the user's text editor of choice e.g. VSCode, Vim, Emacs etc +- On the right we have the webview used to show the preview of the user's documentation. + In the case of VSCode this is probably a built-in webview, but for other editors it's most likely to be a web browser. +- In the center there is the ``esbonio`` language server itself with two additional components. + + - A HTTP server, used to serve files out of the build directory + - A WebSocket server, used for communication between the language server and the webview. + +Typical Workflow +---------------- + +At a high level the typical interaction between the components may look something like the following. + +#. The user previews a given file in their editor. +#. If it hasn't done so already, the language server creates a WebSocket server to listen for connections from a webview. +#. If it hasn't done so already, the language server creates a HTTP server and configures it to serve content out of the relevant build directory. +#. The server informs the editor the url at which the preview server can be found and the webview is opened. +#. Once the page loads in the webview, the WebSocket client embedded in the page connects to the WebSocket server running in the Language Server. + Using the Language Server as an intermediary, it's now possible for the editor and webview to communicate with each other. +#. When the user scrolls the editor, the editor informs the webview where it should scroll to (and vice versa).