diff --git a/docs/source/clients/index.rst b/docs/source/clients/index.rst new file mode 100644 index 00000000..e2a2993d --- /dev/null +++ b/docs/source/clients/index.rst @@ -0,0 +1,2 @@ +Coming Soon\ :sup:`TM` +====================== diff --git a/docs/source/index.rst b/docs/source/index.rst index 08db13f2..01e79516 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,12 +18,30 @@ allows you to write your own `language server`_ in just a few lines of code .. toctree:: :hidden: - :caption: User Guide + :caption: Language Servers - getting-started - user-guide - How To - reference + servers/getting-started + servers/user-guide + How To + +.. toctree:: + :hidden: + :caption: Language Clients + + clients/index + +.. toctree:: + :hidden: + :caption: The Protocol + + protocol/howto + +.. toctree:: + :hidden: + :caption: The Library + + pygls/howto + pygls/reference .. toctree:: :hidden: @@ -39,34 +57,54 @@ allows you to write your own `language server`_ in just a few lines of code history changelog +Navigation +---------- + +*The pygls documentation tries to (with varying degrees of success!) follow the* `Diátaxis `__ *approach to writing documentation* -The documentation is divided up into the following sections +This documentation site is divided up into the following sections .. grid:: 1 2 2 2 :gutter: 2 - .. grid-item-card:: Getting Started - :link: /getting-started + .. grid-item-card:: Language Servers + :link: servers/getting-started :link-type: doc :text-align: center - First steps with *pygls*. + Documentation specific to implementing Language Servers using *pygls*. + + .. grid-item-card:: Language Clients + :text-align: center + + Documentation specific to implementing Language Clients using *pygls*. + Coming Soon\ :sup:`TM`! - .. grid-item-card:: How To Guides - :link: /howto + .. grid-item-card:: The Protocol + :link: protocol/howto :link-type: doc :text-align: center - Short, focused articles on how to acheive a particular outcome + Additional articles that explain some aspect of the Language Server Protocol in general. - .. grid-item-card:: API Reference - :link: /reference + .. grid-item-card:: The Library + :link: pygls/howto :link-type: doc - :columns: 12 :text-align: center - Comprehensive, detailed documentation on all of the features provided by *pygls*. + Documentation that applies to the *pygls* library itself e.g. migration guides. + + .. grid-item-card:: Contributing + :link: contributing/howto + :link-type: doc + :text-align: center + + Guides on how to contribute to *pygls*. + + .. grid-item-card:: About + :text-align: center + Additional context on the *pygls* project. .. _Language Server Protocol: https://microsoft.github.io/language-server-protocol/specification .. _Language server: https://langserver.org/ diff --git a/docs/source/protocol/howto.rst b/docs/source/protocol/howto.rst new file mode 100644 index 00000000..4059416e --- /dev/null +++ b/docs/source/protocol/howto.rst @@ -0,0 +1,8 @@ +How To +====== + +.. toctree:: + :maxdepth: 1 + :glob: + + Interpret Semantic Tokens diff --git a/docs/source/howto/implement-semantic-tokens.rst b/docs/source/protocol/howto/interpret-semantic-tokens.rst similarity index 97% rename from docs/source/howto/implement-semantic-tokens.rst rename to docs/source/protocol/howto/interpret-semantic-tokens.rst index 12ab467c..a6bd6202 100644 --- a/docs/source/howto/implement-semantic-tokens.rst +++ b/docs/source/protocol/howto/interpret-semantic-tokens.rst @@ -1,8 +1,16 @@ .. _howto-semantic-tokens: -How To Implement Semantic Tokens +How To Interpret Semantic Tokens ================================ +.. seealso:: + + :ref:`Example Server ` + An example implementation of semantic tokens + + :lsp:`textDocument/semanticTokens` + Semantic tokens in the LSP Specification + Semantic Tokens can be thought of as "Syntax Highlighting++". Traditional syntax highlighting is usually implemented as a large collection of :mod:`regular expressions ` and can use the language's grammar rules to tell the difference between say a string, variable or function. @@ -98,15 +106,7 @@ To quote the specification: Finally! We have managed to construct the values we need to apply semantic tokens to the snippet of code we considered at the start -.. figure:: ../../assets/semantic-tokens-example.png +.. figure:: ../../../assets/semantic-tokens-example.png :align: center Our semantic tokens example implemented in VSCode - -.. seealso:: - - :ref:`Example Server ` - An example implementation of semantic tokens - - :lsp:`textDocument/semanticTokens` - Semantic tokens in the LSP Specification diff --git a/docs/source/howto/tokens/modifiers.html b/docs/source/protocol/howto/tokens/modifiers.html similarity index 100% rename from docs/source/howto/tokens/modifiers.html rename to docs/source/protocol/howto/tokens/modifiers.html diff --git a/docs/source/howto/tokens/positions.html b/docs/source/protocol/howto/tokens/positions.html similarity index 100% rename from docs/source/howto/tokens/positions.html rename to docs/source/protocol/howto/tokens/positions.html diff --git a/docs/source/howto/tokens/types.html b/docs/source/protocol/howto/tokens/types.html similarity index 100% rename from docs/source/howto/tokens/types.html rename to docs/source/protocol/howto/tokens/types.html diff --git a/docs/source/pygls/howto.rst b/docs/source/pygls/howto.rst new file mode 100644 index 00000000..123d3139 --- /dev/null +++ b/docs/source/pygls/howto.rst @@ -0,0 +1,9 @@ +How To +====== + +.. toctree:: + :maxdepth: 1 + :glob: + + Migrate to v1 + Migrate to v2 diff --git a/docs/source/howto/migrate-to-v1.rst b/docs/source/pygls/howto/migrate-to-v1.rst similarity index 100% rename from docs/source/howto/migrate-to-v1.rst rename to docs/source/pygls/howto/migrate-to-v1.rst diff --git a/docs/source/howto/migrate-to-v2.rst b/docs/source/pygls/howto/migrate-to-v2.rst similarity index 100% rename from docs/source/howto/migrate-to-v2.rst rename to docs/source/pygls/howto/migrate-to-v2.rst diff --git a/docs/source/pygls/reference.rst b/docs/source/pygls/reference.rst new file mode 100644 index 00000000..4ac7f02a --- /dev/null +++ b/docs/source/pygls/reference.rst @@ -0,0 +1,63 @@ +Python API +========== + +In this section you will find reference documentation on pygls' Python API + +.. toctree:: + :hidden: + :glob: + + reference/* + + +.. grid:: 1 2 2 2 + :gutter: 2 + + .. grid-item-card:: Clients + :link: reference/clients + :link-type: doc + :text-align: center + + pygls' Language Client APIs. + + .. grid-item-card:: Servers + :link: reference/servers + :link-type: doc + :text-align: center + + pygls' Language Server APIs + + .. grid-item-card:: LSP Types + :link: reference/types + :link-type: doc + :text-align: center + + LSP type definitions, as provided by the *lsprotocol* library + + .. grid-item-card:: URIs + :link: reference/types + :link-type: doc + :text-align: center + + Helper functions for working with URIs + + .. grid-item-card:: Workspace + :link: reference/workspace + :link-type: doc + :text-align: center + + pygls' workspace API + + .. grid-item-card:: Protocol + :link: reference/protocol + :link-type: doc + :text-align: center + + pygls' low-level protocol APIs + + .. grid-item-card:: IO + :link: reference/io + :link-type: doc + :text-align: center + + pygls' low-level input/output APIs diff --git a/docs/source/reference/clients.rst b/docs/source/pygls/reference/clients.rst similarity index 100% rename from docs/source/reference/clients.rst rename to docs/source/pygls/reference/clients.rst diff --git a/docs/source/pygls/reference/io.rst b/docs/source/pygls/reference/io.rst new file mode 100644 index 00000000..3bf37bd5 --- /dev/null +++ b/docs/source/pygls/reference/io.rst @@ -0,0 +1,6 @@ +IO +== + + +.. automodule:: pygls.io_ + :members: diff --git a/docs/source/reference/protocol.rst b/docs/source/pygls/reference/protocol.rst similarity index 100% rename from docs/source/reference/protocol.rst rename to docs/source/pygls/reference/protocol.rst diff --git a/docs/source/reference/servers.rst b/docs/source/pygls/reference/servers.rst similarity index 100% rename from docs/source/reference/servers.rst rename to docs/source/pygls/reference/servers.rst diff --git a/docs/source/reference/types.rst b/docs/source/pygls/reference/types.rst similarity index 100% rename from docs/source/reference/types.rst rename to docs/source/pygls/reference/types.rst diff --git a/docs/source/reference/uris.rst b/docs/source/pygls/reference/uris.rst similarity index 100% rename from docs/source/reference/uris.rst rename to docs/source/pygls/reference/uris.rst diff --git a/docs/source/reference/workspace.rst b/docs/source/pygls/reference/workspace.rst similarity index 100% rename from docs/source/reference/workspace.rst rename to docs/source/pygls/reference/workspace.rst diff --git a/docs/source/reference.rst b/docs/source/reference.rst deleted file mode 100644 index 04312347..00000000 --- a/docs/source/reference.rst +++ /dev/null @@ -1,8 +0,0 @@ -API Reference -============= - -.. toctree:: - :maxdepth: 1 - :glob: - - reference/* diff --git a/docs/source/examples/code-actions.rst b/docs/source/servers/examples/code-actions.rst similarity index 100% rename from docs/source/examples/code-actions.rst rename to docs/source/servers/examples/code-actions.rst diff --git a/docs/source/examples/code-lens.rst b/docs/source/servers/examples/code-lens.rst similarity index 100% rename from docs/source/examples/code-lens.rst rename to docs/source/servers/examples/code-lens.rst diff --git a/docs/source/examples/colors.rst b/docs/source/servers/examples/colors.rst similarity index 100% rename from docs/source/examples/colors.rst rename to docs/source/servers/examples/colors.rst diff --git a/docs/source/examples/formatting.rst b/docs/source/servers/examples/formatting.rst similarity index 100% rename from docs/source/examples/formatting.rst rename to docs/source/servers/examples/formatting.rst diff --git a/docs/source/examples/goto.rst b/docs/source/servers/examples/goto.rst similarity index 100% rename from docs/source/examples/goto.rst rename to docs/source/servers/examples/goto.rst diff --git a/docs/source/examples/hover.rst b/docs/source/servers/examples/hover.rst similarity index 100% rename from docs/source/examples/hover.rst rename to docs/source/servers/examples/hover.rst diff --git a/docs/source/examples/inlay-hints.rst b/docs/source/servers/examples/inlay-hints.rst similarity index 100% rename from docs/source/examples/inlay-hints.rst rename to docs/source/servers/examples/inlay-hints.rst diff --git a/docs/source/examples/json-server.rst b/docs/source/servers/examples/json-server.rst similarity index 100% rename from docs/source/examples/json-server.rst rename to docs/source/servers/examples/json-server.rst diff --git a/docs/source/examples/links.rst b/docs/source/servers/examples/links.rst similarity index 100% rename from docs/source/examples/links.rst rename to docs/source/servers/examples/links.rst diff --git a/docs/source/examples/publish-diagnostics.rst b/docs/source/servers/examples/publish-diagnostics.rst similarity index 100% rename from docs/source/examples/publish-diagnostics.rst rename to docs/source/servers/examples/publish-diagnostics.rst diff --git a/docs/source/examples/pull-diagnostics.rst b/docs/source/servers/examples/pull-diagnostics.rst similarity index 100% rename from docs/source/examples/pull-diagnostics.rst rename to docs/source/servers/examples/pull-diagnostics.rst diff --git a/docs/source/examples/rename.rst b/docs/source/servers/examples/rename.rst similarity index 100% rename from docs/source/examples/rename.rst rename to docs/source/servers/examples/rename.rst diff --git a/docs/source/examples/semantic-tokens.rst b/docs/source/servers/examples/semantic-tokens.rst similarity index 100% rename from docs/source/examples/semantic-tokens.rst rename to docs/source/servers/examples/semantic-tokens.rst diff --git a/docs/source/examples/symbols.rst b/docs/source/servers/examples/symbols.rst similarity index 100% rename from docs/source/examples/symbols.rst rename to docs/source/servers/examples/symbols.rst diff --git a/docs/source/examples/threaded-handlers.rst b/docs/source/servers/examples/threaded-handlers.rst similarity index 100% rename from docs/source/examples/threaded-handlers.rst rename to docs/source/servers/examples/threaded-handlers.rst diff --git a/docs/source/getting-started.rst b/docs/source/servers/getting-started.rst similarity index 82% rename from docs/source/getting-started.rst rename to docs/source/servers/getting-started.rst index bdfba7cb..4851c24d 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/servers/getting-started.rst @@ -22,91 +22,91 @@ Each of the following example servers are focused on implementing a particular s :gutter: 2 .. grid-item-card:: Code Actions - :link: /examples/code-actions + :link: examples/code-actions :link-type: doc :text-align: center :octicon:`light-bulb` .. grid-item-card:: Code Lens - :link: /examples/code-lens + :link: examples/code-lens :link-type: doc :text-align: center :octicon:`eye` .. grid-item-card:: Colors - :link: /examples/colors + :link: examples/colors :link-type: doc :text-align: center :octicon:`paintbrush` .. grid-item-card:: Formatting - :link: /examples/formatting + :link: examples/formatting :link-type: doc :text-align: center :octicon:`typography` .. grid-item-card:: Goto "X" - :link: /examples/goto + :link: examples/goto :link-type: doc :text-align: center :octicon:`search` .. grid-item-card:: Hover - :link: /examples/hover + :link: examples/hover :link-type: doc :text-align: center :octicon:`book` .. grid-item-card:: Inlay Hints - :link: /examples/inlay-hints + :link: examples/inlay-hints :link-type: doc :text-align: center :octicon:`info` .. grid-item-card:: Links - :link: /examples/links + :link: examples/links :link-type: doc :text-align: center :octicon:`link` .. grid-item-card:: Publish Diagnostics - :link: /examples/publish-diagnostics + :link: examples/publish-diagnostics :link-type: doc :text-align: center :octicon:`alert` .. grid-item-card:: Pull Diagnostics - :link: /examples/pull-diagnostics + :link: examples/pull-diagnostics :link-type: doc :text-align: center :octicon:`alert` .. grid-item-card:: Rename - :link: /examples/rename + :link: examples/rename :link-type: doc :text-align: center :octicon:`pencil` .. grid-item-card:: Semantic Tokens - :link: /examples/semantic-tokens + :link: examples/semantic-tokens :link-type: doc :text-align: center :octicon:`file-binary` .. grid-item-card:: Symbols - :link: /examples/symbols + :link: examples/symbols :link-type: doc :text-align: center @@ -118,14 +118,14 @@ These servers are dedicated to demonstrating features of *pygls* itself :gutter: 2 .. grid-item-card:: JSON Server - :link: /examples/json-server + :link: examples/json-server :link-type: doc :text-align: center :octicon:`code` .. grid-item-card:: Threaded Handlers - :link: /examples/threaded-handlers + :link: examples/threaded-handlers :link-type: doc :text-align: center diff --git a/docs/source/howto.rst b/docs/source/servers/howto.rst similarity index 54% rename from docs/source/howto.rst rename to docs/source/servers/howto.rst index 71d32960..13cb2555 100644 --- a/docs/source/howto.rst +++ b/docs/source/servers/howto.rst @@ -5,7 +5,4 @@ How To Guides :maxdepth: 1 Handle Invalid Data - Implement Semantic Tokens - Migrate to v1 - Migrate to v2 Use the pygls-playground diff --git a/docs/source/howto/handle-invalid-data.rst b/docs/source/servers/howto/handle-invalid-data.rst similarity index 100% rename from docs/source/howto/handle-invalid-data.rst rename to docs/source/servers/howto/handle-invalid-data.rst diff --git a/docs/source/howto/use-the-pygls-playground.rst b/docs/source/servers/howto/use-the-pygls-playground.rst similarity index 100% rename from docs/source/howto/use-the-pygls-playground.rst rename to docs/source/servers/howto/use-the-pygls-playground.rst diff --git a/docs/source/tutorial.rst b/docs/source/servers/tutorial.rst similarity index 100% rename from docs/source/tutorial.rst rename to docs/source/servers/tutorial.rst diff --git a/docs/source/tutorial/0-setup.rst b/docs/source/servers/tutorial/0-setup.rst similarity index 100% rename from docs/source/tutorial/0-setup.rst rename to docs/source/servers/tutorial/0-setup.rst diff --git a/docs/source/tutorial/y-testing.rst b/docs/source/servers/tutorial/y-testing.rst similarity index 100% rename from docs/source/tutorial/y-testing.rst rename to docs/source/servers/tutorial/y-testing.rst diff --git a/docs/source/tutorial/z-next-steps.rst b/docs/source/servers/tutorial/z-next-steps.rst similarity index 100% rename from docs/source/tutorial/z-next-steps.rst rename to docs/source/servers/tutorial/z-next-steps.rst diff --git a/docs/source/user-guide.rst b/docs/source/servers/user-guide.rst similarity index 100% rename from docs/source/user-guide.rst rename to docs/source/servers/user-guide.rst diff --git a/examples/servers/symbols.py b/examples/servers/symbols.py index 1e4c4a24..3a565d75 100644 --- a/examples/servers/symbols.py +++ b/examples/servers/symbols.py @@ -30,7 +30,7 @@ This server implements these requests for the pretend programming language featured in the ``code.txt`` in the example workspace in the *pygls* repository. -.. literalinclude:: ../../../examples/servers/workspace/code.txt +.. literalinclude:: ../../../../examples/servers/workspace/code.txt :language: none """