docs: restructure the documentation... again

This commit attempts to add a bit more structure to the documentation, hopefully making it easier to navigate as the number of articles slowly grows
openlawlibrary · Oct 28, 2024 · b880eaa · b880eaa
1 parent eb1cc03
commit b880eaa
Show file tree

Hide file tree

Showing 44 changed files with 168 additions and 53 deletions.
diff --git a/docs/source/clients/index.rst 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
@@ -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 <howto>
-   reference
+   servers/getting-started
+   servers/user-guide
+   How To <servers/howto>
+
+.. 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 <https://diataxis.fr/>`__ *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
@@ -0,0 +1,8 @@
+How To
+======
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   Interpret Semantic Tokens <howto/interpret-semantic-tokens>
diff --git a/...ource/howto/implement-semantic-tokens.rst → ...tocol/howto/interpret-semantic-tokens.rst b/...ource/howto/implement-semantic-tokens.rst → ...tocol/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 <example-semantic-tokens>`
+      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 <python:re>` 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 <example-semantic-tokens>`
-      An example implementation of semantic tokens
-
-   :lsp:`textDocument/semanticTokens`
-      Semantic tokens in the LSP Specification
diff --git a/docs/source/howto/tokens/modifiers.html → ...urce/protocol/howto/tokens/modifiers.html b/docs/source/howto/tokens/modifiers.html → ...urce/protocol/howto/tokens/modifiers.html
diff --git a/docs/source/howto/tokens/positions.html → ...urce/protocol/howto/tokens/positions.html b/docs/source/howto/tokens/positions.html → ...urce/protocol/howto/tokens/positions.html
diff --git a/docs/source/howto/tokens/types.html → docs/source/protocol/howto/tokens/types.html b/docs/source/howto/tokens/types.html → docs/source/protocol/howto/tokens/types.html
diff --git a/docs/source/pygls/howto.rst b/docs/source/pygls/howto.rst
@@ -0,0 +1,9 @@
+How To
+======
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   Migrate to v1 <howto/migrate-to-v1>
+   Migrate to v2 <howto/migrate-to-v2>
diff --git a/docs/source/howto/migrate-to-v1.rst → docs/source/pygls/howto/migrate-to-v1.rst b/docs/source/howto/migrate-to-v1.rst → docs/source/pygls/howto/migrate-to-v1.rst
diff --git a/docs/source/howto/migrate-to-v2.rst → docs/source/pygls/howto/migrate-to-v2.rst b/docs/source/howto/migrate-to-v2.rst → docs/source/pygls/howto/migrate-to-v2.rst
diff --git a/docs/source/pygls/reference.rst 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 → docs/source/pygls/reference/clients.rst b/docs/source/reference/clients.rst → docs/source/pygls/reference/clients.rst
diff --git a/docs/source/pygls/reference/io.rst b/docs/source/pygls/reference/io.rst
@@ -0,0 +1,6 @@
+IO
+==
+
+
+.. automodule:: pygls.io_
+   :members:
diff --git a/docs/source/reference/protocol.rst → docs/source/pygls/reference/protocol.rst b/docs/source/reference/protocol.rst → docs/source/pygls/reference/protocol.rst
diff --git a/docs/source/reference/servers.rst → docs/source/pygls/reference/servers.rst b/docs/source/reference/servers.rst → docs/source/pygls/reference/servers.rst
diff --git a/docs/source/reference/types.rst → docs/source/pygls/reference/types.rst b/docs/source/reference/types.rst → docs/source/pygls/reference/types.rst
diff --git a/docs/source/reference/uris.rst → docs/source/pygls/reference/uris.rst b/docs/source/reference/uris.rst → docs/source/pygls/reference/uris.rst
diff --git a/docs/source/reference/workspace.rst → docs/source/pygls/reference/workspace.rst b/docs/source/reference/workspace.rst → docs/source/pygls/reference/workspace.rst
diff --git a/docs/source/reference.rst b/docs/source/reference.rst
diff --git a/docs/source/examples/code-actions.rst → .../source/servers/examples/code-actions.rst b/docs/source/examples/code-actions.rst → .../source/servers/examples/code-actions.rst
diff --git a/docs/source/examples/code-lens.rst → docs/source/servers/examples/code-lens.rst b/docs/source/examples/code-lens.rst → docs/source/servers/examples/code-lens.rst
diff --git a/docs/source/examples/colors.rst → docs/source/servers/examples/colors.rst b/docs/source/examples/colors.rst → docs/source/servers/examples/colors.rst
diff --git a/docs/source/examples/formatting.rst → docs/source/servers/examples/formatting.rst b/docs/source/examples/formatting.rst → docs/source/servers/examples/formatting.rst
diff --git a/docs/source/examples/goto.rst → docs/source/servers/examples/goto.rst b/docs/source/examples/goto.rst → docs/source/servers/examples/goto.rst
diff --git a/docs/source/examples/hover.rst → docs/source/servers/examples/hover.rst b/docs/source/examples/hover.rst → docs/source/servers/examples/hover.rst
diff --git a/docs/source/examples/inlay-hints.rst → docs/source/servers/examples/inlay-hints.rst b/docs/source/examples/inlay-hints.rst → docs/source/servers/examples/inlay-hints.rst
diff --git a/docs/source/examples/json-server.rst → docs/source/servers/examples/json-server.rst b/docs/source/examples/json-server.rst → docs/source/servers/examples/json-server.rst
diff --git a/docs/source/examples/links.rst → docs/source/servers/examples/links.rst b/docs/source/examples/links.rst → docs/source/servers/examples/links.rst
diff --git a/docs/source/examples/publish-diagnostics.rst → .../servers/examples/publish-diagnostics.rst b/docs/source/examples/publish-diagnostics.rst → .../servers/examples/publish-diagnostics.rst
diff --git a/docs/source/examples/pull-diagnostics.rst → ...rce/servers/examples/pull-diagnostics.rst b/docs/source/examples/pull-diagnostics.rst → ...rce/servers/examples/pull-diagnostics.rst
diff --git a/docs/source/examples/rename.rst → docs/source/servers/examples/rename.rst b/docs/source/examples/rename.rst → docs/source/servers/examples/rename.rst
diff --git a/docs/source/examples/semantic-tokens.rst → ...urce/servers/examples/semantic-tokens.rst b/docs/source/examples/semantic-tokens.rst → ...urce/servers/examples/semantic-tokens.rst
diff --git a/docs/source/examples/symbols.rst → docs/source/servers/examples/symbols.rst b/docs/source/examples/symbols.rst → docs/source/servers/examples/symbols.rst
diff --git a/docs/source/examples/threaded-handlers.rst → ...ce/servers/examples/threaded-handlers.rst b/docs/source/examples/threaded-handlers.rst → ...ce/servers/examples/threaded-handlers.rst
diff --git a/docs/source/getting-started.rst → docs/source/servers/getting-started.rst b/docs/source/getting-started.rst → 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 → docs/source/servers/howto.rst b/docs/source/howto.rst → docs/source/servers/howto.rst
@@ -5,7 +5,4 @@ How To Guides
    :maxdepth: 1
 
    Handle Invalid Data <howto/handle-invalid-data>
-   Implement Semantic Tokens <howto/implement-semantic-tokens>
-   Migrate to v1 <howto/migrate-to-v1>
-   Migrate to v2 <howto/migrate-to-v2>
    Use the pygls-playground <howto/use-the-pygls-playground>
diff --git a/docs/source/howto/handle-invalid-data.rst → ...rce/servers/howto/handle-invalid-data.rst b/docs/source/howto/handle-invalid-data.rst → ...rce/servers/howto/handle-invalid-data.rst
diff --git a/...source/howto/use-the-pygls-playground.rst → ...ervers/howto/use-the-pygls-playground.rst b/...source/howto/use-the-pygls-playground.rst → ...ervers/howto/use-the-pygls-playground.rst
diff --git a/docs/source/tutorial.rst → docs/source/servers/tutorial.rst b/docs/source/tutorial.rst → docs/source/servers/tutorial.rst
diff --git a/docs/source/tutorial/0-setup.rst → docs/source/servers/tutorial/0-setup.rst b/docs/source/tutorial/0-setup.rst → docs/source/servers/tutorial/0-setup.rst
diff --git a/docs/source/tutorial/y-testing.rst → docs/source/servers/tutorial/y-testing.rst b/docs/source/tutorial/y-testing.rst → docs/source/servers/tutorial/y-testing.rst
diff --git a/docs/source/tutorial/z-next-steps.rst → .../source/servers/tutorial/z-next-steps.rst b/docs/source/tutorial/z-next-steps.rst → .../source/servers/tutorial/z-next-steps.rst
diff --git a/docs/source/user-guide.rst → docs/source/servers/user-guide.rst b/docs/source/user-guide.rst → docs/source/servers/user-guide.rst
diff --git 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
 """