diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml new file mode 100644 index 0000000..36f854f --- /dev/null +++ b/.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/ \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..07ed706 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +build/* \ No newline at end of file diff --git a/diplomat-lsp/Makefile b/diplomat-lsp-src/Makefile similarity index 86% rename from diplomat-lsp/Makefile rename to diplomat-lsp-src/Makefile index d0c3cbf..40f2000 100644 --- a/diplomat-lsp/Makefile +++ b/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 diff --git a/diplomat-lsp/make.bat b/diplomat-lsp-src/make.bat similarity index 100% rename from diplomat-lsp/make.bat rename to diplomat-lsp-src/make.bat diff --git a/diplomat-lsp-src/requirements.txt b/diplomat-lsp-src/requirements.txt new file mode 100644 index 0000000..7b0ab48 --- /dev/null +++ b/diplomat-lsp-src/requirements.txt @@ -0,0 +1 @@ +furo==2024.7.18 \ No newline at end of file diff --git a/diplomat-lsp/source/conf.py b/diplomat-lsp-src/source/conf.py similarity index 96% rename from diplomat-lsp/source/conf.py rename to diplomat-lsp-src/source/conf.py index 5662c10..3b31bad 100644 --- a/diplomat-lsp/source/conf.py +++ b/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, diff --git a/diplomat-lsp/source/index.rst b/diplomat-lsp-src/source/index.rst similarity index 91% rename from diplomat-lsp/source/index.rst rename to diplomat-lsp-src/source/index.rst index f8d8c16..b89a24e 100644 --- a/diplomat-lsp/source/index.rst +++ b/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 diff --git a/diplomat-lsp-src/source/lsp/custom_lsp.rst b/diplomat-lsp-src/source/lsp/custom_lsp.rst new file mode 100644 index 0000000..7b105b4 --- /dev/null +++ b/diplomat-lsp-src/source/lsp/custom_lsp.rst @@ -0,0 +1,3 @@ +Custom Language Server commands +=============================== + diff --git a/diplomat-lsp-src/source/lsp/presentation.rst b/diplomat-lsp-src/source/lsp/presentation.rst new file mode 100644 index 0000000..f16db4c --- /dev/null +++ b/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 `_ to perform code analysis and elaboration. + +.. toctree:: + :maxdepth: 2 + :caption: Content: + + standard_lsp + custom_lsp \ No newline at end of file diff --git a/diplomat-lsp-src/source/lsp/standard_lsp.rst b/diplomat-lsp-src/source/lsp/standard_lsp.rst new file mode 100644 index 0000000..cb31d57 --- /dev/null +++ b/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 `_ +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 `_ + +``initialized`` notification +------------------------------ +See `the LSP specification for 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 `_ + +``shutdown`` request +---------------------- +See `the LSP specification for shutdown `_ + +``textDocument/didOpen`` notification +----------------------------------------------------- + + +``textDocument/didSave`` notification +----------------------------------------------------- +See `the LSP specification for 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 `_ + +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 +----------------------------------------------------- + diff --git a/diplomat-lsp-src/source/vscode/presentation.rst b/diplomat-lsp-src/source/vscode/presentation.rst new file mode 100644 index 0000000..1b23915 --- /dev/null +++ b/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 `_ 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 \ No newline at end of file