Setup

.github/workflows/sphinx.yml

@@ -0,0 +1,27 @@
+name: "Sphinx: Render docs"
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v4
+    - name: Build HTML
+      uses: ammaraskar/sphinx-action@master
+      with:
+        docs-folder: "diplomat-lsp-src/"
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: html-docs
+        path: diplomat-lsp-src/build/html
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/master'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: diplomat-lsp-src/build/html
+        destination_dir: diplomat-lsp/

.gitignore

@@ -0,0 +1 @@
+build/*

diplomat-lsp/Makefile → diplomat-lsp-src/Makefile

@@ -14,6 +14,10 @@ help:
 
 .PHONY: help Makefile
 
+
+# html: Makefile
+# 	@$(SPHINXBUILD) -E -a -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

diplomat-lsp-src/requirements.txt

@@ -0,0 +1 @@
+furo==2024.7.18

diplomat-lsp/source/conf.py → diplomat-lsp-src/source/conf.py

@@ -17,7 +17,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'Diplomat Documentation'
+project = 'Diplomat LSP'
 copyright = '2024, Julien FAUCHER'
 author = 'Julien FAUCHER'
 
@@ -47,7 +47,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'furo'
 
 # 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,

diplomat-lsp/source/index.rst → diplomat-lsp-src/source/index.rst

@@ -10,6 +10,8 @@ Welcome to Diplomat Documentation's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   vscode/presentation
+   lsp/presentation
 
 
 Indices and tables

diplomat-lsp-src/source/lsp/custom_lsp.rst

@@ -0,0 +1,3 @@
+Custom Language Server commands
+===============================
+

diplomat-lsp-src/source/lsp/presentation.rst

@@ -0,0 +1,12 @@
+Diplomat Language Server
+========================
+
+The Diplomat language server is a full C++ implementation of the *Language Server Protocol* (LSP) targetting SystemVerilog.
+It relies on `slang <https://github.com/MikePopoloski/slang>`_ to perform code analysis and elaboration.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Content:
+
+   standard_lsp
+   custom_lsp

diplomat-lsp-src/source/lsp/standard_lsp.rst

@@ -0,0 +1,71 @@
+Supported standard LSP commands
+===============================
+
+The commands provided here are standard commands from the `Language Server Protocol specification <https://microsoft.github.io/language-server-protocol/>`_
+The server will reply accordingly to the standard to the requests listed bellow.
+Other request will be ignored.
+
+As of today, the language server implements the standard version 3.17
+
+``initialize`` request
+----------------------
+See `the LSP specification for initialize <https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#initialize>`_
+
+``initialized`` notification
+------------------------------
+See `the LSP specification for initialized <https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#initialized>`_
+
+Upon receiving this notification, the language server will request some configurations if the ``workspace/configuration`` request is 
+supported by the client. 
+
+``exit`` notification
+----------------------
+See `the LSP specification for exit <https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#exit>`_
+
+``shutdown`` request
+----------------------
+See `the LSP specification for shutdown <https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#shutdown>`_
+
+``textDocument/didOpen`` notification
+-----------------------------------------------------
+
+
+``textDocument/didSave`` notification
+-----------------------------------------------------
+See `the LSP specification for textDocument/didSave <https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_didSave>`_
+
+Upon receiving this notification, the language server will re-run a workspace analysis and refresh all diagnostics.
+
+
+``textDocument/definition`` request
+-----------------------------------------------------
+
+
+``textDocument/references`` request
+-----------------------------------------------------
+
+
+``textDocument/rename`` request
+-----------------------------------------------------
+
+
+``textDocument/formatting`` request
+-----------------------------------------------------
+Invoke the internal formatter.
+
+.. warning:: This is under development and the result may not be of great quality.
+
+.. warning:: The range formating is not available and the file shall be saved before running this command.
+
+``workspace/didChangeWorkspaceFolders`` notification
+-----------------------------------------------------
+
+``textDocument/publishDiagnostics`` notification
+-----------------------------------------------------
+See `the LSP specification for textDocument/publishDiagnostics <https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_publishDiagnostics>`_
+
+The ``textDocument/publishDiagnostics`` notification is actually sent by the server in order to provide the diagnostic results after a successful workspace analysis
+
+``workspace/executeCommand`` notification
+-----------------------------------------------------
+

diplomat-lsp-src/source/vscode/presentation.rst

@@ -0,0 +1,13 @@
+Diplomat VSCode extension
+=========================
+
+The Diplomat VSCode extension (*Diplomat Client*, sometimes refered as *Diplomat Host*)
+is the provided client for interfacing with Diplomat Server.
+
+It features:
+ * Workspace analysis using the `slang <https://github.com/MikePopoloski/slang>`_ open source SystemVerilog compiler.
+ * Error checking and elaboration-level linting
+ * Jump to definition/reference across files
+ * Syntax coloration
+ * Rename symbol
+ * Assisted instanciation of any module found in the workspace