docs: wip tutorial

swyddfa · Dec 27, 2023 · c5e083d · c5e083d
1 parent d48ea9d
commit c5e083d
Show file tree

Hide file tree

Showing 3 changed files with 144 additions and 50 deletions.
diff --git a/docs/extensions/relevant_to.rst b/docs/extensions/relevant_to.rst
@@ -10,7 +10,7 @@ Additionally this extension
 - Reflects the chosen topic in the page's URL, making subject choices linkable
 - Uses `htmx`_ to swap out the relevant sections.
 
-See the Esbonio language server's :ref:`lsp_getting_started` guide for an example of this extension in action.
+See the Esbonio language server's :ref:`lsp-getting-started` guide for an example of this extension in action.
 
 .. note::
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -3,13 +3,48 @@ Esbonio
 
 .. rubric:: esbonio -- (v.) to explain
 
-Esbonio aims to make it easier to work with `reStructuredText`_ tools such as
-`Sphinx`_ by providing a `Language Server`_ to enhance your editing experience.
+Esbonio is a `Language Server`_ for `Sphinx`_ documentation projects.
+
+Esbonio aids the writing process by resolving references, providing completion suggestions and highlighting errors.
+It ensures your local build is always up to date, allowing you to preview your changes in (almost!) real-time.
+The server itself can even be extended to better suit the needs of your project.
+
+The primary goal of Esbonio is to reduce the friction that comes from trying to remember the specifics of a markup language, so that you can focus on your content and not your tooling.
+
+.. grid:: 2
+   :gutter: 1
+
+   .. grid-item-card:: Getting Started
+      :text-align: center
+      :link: lsp-getting-started
+      :link-type: ref
+
+      Using Esbonio for the first time within VSCode.
+
+   .. grid-item-card:: How-To Guides
+      :text-align: center
+
+      Step-by-step guides on integrating Esbonio with other text editors.
+
+   .. grid-item-card:: Reference
+      :text-align: center
+      :link: lsp-reference
+      :link-type: ref
+
+      Configuration options, API documentation, architecture diagrams and more.
+
+   .. grid-item-card:: Extending
+      :text-align: center
+      :link: lsp-extending
+      :link-type: ref
+
+      Documentation on extendining the Esbonio language server
+
 
 Language Server
 ---------------
 
-Here is a quick summary of the features implemented by the language server.
+Below are some of the features provided by the language server.
 
 .. collection:: features
 
@@ -74,15 +109,6 @@ Here is a quick summary of the features implemented by the language server.
          :align: center
          :target: /_images/implementation-demo.gif
 
-- See the :ref:`lsp_getting_started` guide for details on how to get up and
-  running.
-
-- For further details on more advanced use cases, see the :ref:`lsp-advanced` section.
-
-- Interested in adding support for your own Sphinx extensions?
-  See the section on :ref:`lsp-extending` for more information.
-
-
 .. toctree::
    :glob:
    :caption: Language Server
@@ -91,6 +117,7 @@ Here is a quick summary of the features implemented by the language server.
 
    lsp/getting-started
    lsp/advanced-usage
+   lsp/how-to
    lsp/extending
    lsp/howto
    lsp/reference

diff --git a/docs/lsp/getting-started.rst b/docs/lsp/getting-started.rst
@@ -1,54 +1,121 @@
-.. _lsp_getting_started:
+.. _lsp-getting-started:
 
 Getting Started
 ===============
 
-.. TODO: simple architecture diagram
+.. highlight:: none
 
-.. toctree::
-   :hidden:
-   :glob:
+This tutorial will guide you through using Esbonio for the first time in VSCode.
+By the end you will have the language server setup with an example documentation site and have tried out features like live previews, completion suggestions and diagnostics.
 
-   editors/*
+It should take around 20 minutes to complete, and the only prerequisites are VSCode and a current Python installtion (3.8+).
 
-This section contains notes on how to use the language server with your text editor of choice.
+.. admonition:: What if I don't use VSCode?
 
-.. admonition:: Don't see your favourite editor?
+   Fear not! Any editor that supports the `language server protocol`_ can be used with Esbonio.
 
-   Feel free to submit a pull request with steps on how to get started or if you're not
-   sure on where to start, `open an issue`_ and we'll help you figure it out.
+   We still recommed you read through this tutorial to get an idea of how things work before heading over to the :ref:`lsp-how-to` section for details on setting Esbonio up with your editor of choice.
 
-.. _open an issue: https://github.com/swyddfa/esbonio/issues/new
+.. _language server protocol: https://microsoft.github.io/language-server-protocol/
 
-.. grid:: 2 2 3 4
-   :gutter: 1
+Project Setup
+-------------
 
-   .. grid-item-card:: Kate
-      :link: editors/kate
-      :link-type: doc
-      :text-align: center
+In order to use Esbonio you first need a Sphinx project.
 
-   .. grid-item-card:: Neovim
-      :link: editors/nvim
-      :link-type: doc
-      :text-align: center
+You are of course free to try Esbonio with one of your existing projects, but for the purposes of this tutorial it's **strongly** recommended that you use the `demo project`_ we have prepared for you.
+The rest of the tutorial is written assuming that you have this project open.
 
-   .. grid-item-card:: Neovim (nvim-lspconfig)
-      :link: editors/nvim-lspconfig
-      :link-type: doc
-      :text-align: center
+#. `Download <https://github.com/swyddfa/esbonio-demo/archive/refs/heads/main.zip>`__ the example project and unpack it into a folder of your choosing.
 
-   .. grid-item-card:: Sublime Text
-      :link: editors/sublime
-      :link-type: doc
-      :text-align: center
+#. Open a terminal in the project folder you just downloaded, create a virtual environment and install its dependencies::
 
-   .. grid-item-card:: Vim
-      :link: editors/vim
-      :link-type: doc
-      :text-align: center
+     $ python -m venv env
+     $ source env/bin/activate
+     (env) $ pip install -r requirements.txt
 
-   .. grid-item-card:: VSCode
-      :link: editors/vscode
-      :link-type: doc
-      :text-align: center
+.. _demo project: https://github.com/swyddfa/esbonio-demo
+
+VSCode Setup
+------------
+
+If you have not done so already you will need to install the `Esbonio <https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio>`__ extension from the VSCode marketplace.
+
+#. Open VSCode
+#. Select the :guilabel:`Extensions` tab on the sidebar (:kbd:`Ctrl+Shift+X`) and search for ``esbonio``
+#. Once you have located the Esbonio extension in the list, click the :guilabel:`Install` button to install it.
+
+.. important::
+
+   Until the ``v1.0`` version of the extension is generally available you will need to install the pre-release version using the dropdown built into the :guilabel:`Install` button.
+
+.. warning::
+
+   If you have other reStructuredText extensions installed, they should be disabled to prevent them from conflicting with Esbonio.
+
+First Steps
+-----------
+
+With both the project and VSCode ready to go it's time to start using Esbonio!
+
+#. In VSCode, goto :menuselection:`File --> Open Folder...` and select the folder containing the demo project you setup at the start of the tutorial.
+
+#. Open the command pallete (:kbd:`Ctrl+Shift+P`) and use the :guilabel:`Python: Select Interpreter...` command to select the virtual environment you created for the demo project.
+
+   .. tip::
+
+      If VSCode does not automatically detect your virtual environment select the :menuselection:`Enter interpreter path ... --> Find ...` option.
+      This will open a file picker, you need to select the **python executable** for your environment, not the folder containing the environment.
+
+      - On Windows this will be something like ``C:\Path\to\project\env\Scripts\python.exe``
+      - On Mac/Linux this will be something like ``/path/to/project/env/bin/python``
+
+#. Now open the ``index.rst`` file.
+   Esbonio will automatically launch Sphinx for you in the background.
+
+#. Open the live preview by using the :kbd:`Ctrl+k v` keyboard shortcut (this may take a few seconds to load).
+
+#. Locate the comment ``.. Enter your text here...`` inside of ``index.rst``.
+   Try deleting it and writing ``Hello, World!`` there instead.
+
+Notice that after a few seconds the preview updates to reflect your changes?
+Esbonio will continuously update the preview to give you fast feedback on the changes you are making.
+
+.. important::
+
+   Don't forget to actually save your files from time to time!
+   Or enable the ``files.autoSave`` option for ``restructuredtext`` files inside of VSCode.
+
+Output
+------
+
+We mentioned briefly that Esbonio is running Sphinx for you in the background - let's verify that.
+Open the command palette (:kbd:`Ctrl+Shift+P`) and choose :menuselection:`Output: Show Output Channels... --> Esbonio`.
+
+This should reveal Sphinx's build output in the lower portion of the VSCode window.
+You will notice that the build output is currently being placed in a cache folder [#1]_ somewhere on your system.
+
+Make a change and see the output
+Make a change that includes an error and see the error output
+Fix the error
+
+What next?
+
+Configuration
+-------------
+At present, Sphinx is saving the files… we need to do better…
+Go to Settings (Command , for mac OS,)  > Workspace >
+
+
+.. code-block:: json
+
+   {
+      "esbonio.sphinx.buildCommand": [
+         "sphinx-build", "-M", "dirhtml", ".", "_build"
+      ]
+   }
+
+
+now in the file explorer open the ``_build/`` folder.
+
+.. [#1] as determined by `platformdirs <https://github.com/platformdirs/platformdirs>`__