Implement Docs - Sphinx (nextcord#12)

* Add Sphinx

* Remove the license from the documentation pages

* Update license word check

* Add basic docs

* Add examples.rst

* Add .readthedocs.yaml to automate documentation generation

* Add a guide for how to setup read the docs

* Update the guide

* Update the guide further

* add deploy workflow

* update setup.py

whoops

* Clean .gitignore

* Remove built docs

* Clean conf.py

* Remove requested files

* Update requested files

* Resolve sphinx build errors

* Blacked code

* Update .readthedocs.yaml

* Update relevant directives

* Add errors.rst

* Add documentation to server.py

* Appease linter

* Fix spelling

* Push fixed references

They break locally but I think thats my machine.

* Change to local ref

* update server.py

* Update conf.py

* Resolve server.rst backticks

* Add examples to examples.rst

* Update discord/ext/ipc/client.py

Co-authored-by: Riley Shaw <[email protected]>

* Add `version` to conf.py

* Blacked code

Co-authored-by: Riley Shaw <[email protected]>
Co-authored-by: Logan <[email protected]>

Author: 3 people

.github/workflows/deploy.yml

@@ -0,0 +1,25 @@
+name: Deploy
+
+on: [pull_request, push]
+
+jobs:
+  job:
+    name: Deploy
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Set up Python 3.7
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.7
+
+    - name: Install dependencies
+      run: |-
+        python -m pip install --upgrade pip
+        python -m pip install --upgrade .[docs]
+
+    - name: Build documentation
+      run: sphinx-build -n -W -b html ./docs ./docs/build

.readthedocs.yaml

@@ -0,0 +1,12 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  version: 3.7
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

discord/ext/ipc/client.py

@@ -20,14 +20,17 @@
 
 
 class Client:
-    """Handles webserver side requests to the bot process.
-
-    :param host: The IP or host of the IPC server, defaults to localhost
-    :type host: ``str``, optional
-    :param port: The port of the IPC server. If not supplied the port will be found automatically, defaults to None
-    :type port: ``int``, optional
-    :param secret_key: The secret key for your IPC server. Must match the server secret_key or requests will not go ahead, defaults to None
-    :type secret_key: ``Union[str, bytes]``, optional
+    """
+    Handles webserver side requests to the bot process.
+    
+    Parameters
+    ----------
+    host: str
+        The IP or host of the IPC server, defaults to localhost
+    port: int
+        The port of the IPC server. If not supplied the port will be found automatically, defaults to None
+    secret_key: Union[str, bytes]
+        The secret key for your IPC server. Must match the server secret_key or requests will not go ahead, defaults to None
     """
 
     def __init__(
@@ -56,8 +59,10 @@ def __init__(
     async def init_sock(self):
         """Attempts to connect to the server
 
-        :return: The websocket connection to the server
-        :rtype: ``Websocket``
+        Returns
+        -------
+        :class:`~aiohttp.ClientWebSocketResponse`
+            The websocket connection to the server
         """
         self.session = aiohttp.ClientSession()
 
@@ -86,10 +91,13 @@ async def init_sock(self):
     async def request(self, endpoint: str, **kwargs):
         """Make a request to the IPC server process.
 
-        :param endpoint: The endpoint to request on the server
-        :type endpoint: str
-        :param **kwargs: The data to send to the endpoint
-        :type **kwargs: ``Any``, optional"""
+        Parameters
+        ----------
+        endpoint: str
+            The endpoint to request on the server
+        **kwargs
+            The data to send to the endpoint
+        """
         if not self.session:
             await self.init_sock()
 

discord/ext/ipc/server.py

@@ -17,8 +17,17 @@
 from discord.ext.ipc.errors import *
 
 
-def route(name=None):
-    """Used to register a coroutine as an endpoint"""
+def route(name: str = None):
+    """
+    Used to register a coroutine as an endpoint when you don't have
+    access to an instance of :class:`.Server`
+
+    Parameters
+    ----------
+    name: str
+        The endpoint name. If not provided the method name will be
+        used.
+    """
 
     def decorator(func):
         if not name:
@@ -32,9 +41,7 @@ def decorator(func):
 
 
 class IpcServerResponse:
-    """Format the json data parsed into a nice object"""
-
-    def __init__(self, data):
+    def __init__(self, data: dict):
         self._json = data
         self.length = len(data)
 
@@ -44,7 +51,6 @@ def __init__(self, data):
             setattr(self, key, value)
 
     def to_json(self):
-        """Convert object to json"""
         return self._json
 
     def __repr__(self):
@@ -55,6 +61,26 @@ def __str__(self):
 
 
 class Server:
+    """The IPC server. Usually used on the bot process for receiving
+    requests from the client.
+
+    Attributes
+    ----------
+    bot: :class:`~discord.ext.commands.Bot`
+        Your bot instance
+    host: str
+        The host to run the IPC Server on. Defaults to localhost.
+    port: int
+        The port to run the IPC Server on. Defaults to 8765.
+    secret_key: str
+        A secret key. Used for authentication and should be the same as
+        your client's secret key.
+    do_multicast: bool
+        Turn multicasting on/off. Defaults to True
+    multicast_port: int
+        The port to run the multicasting server on. Defaults to 20000
+    """
+
     ROUTES = {}
 
     def __init__(
@@ -82,8 +108,15 @@ def __init__(
 
         self.endpoints = {}
 
-    def route(self, name=None):
-        """Used to register a coroutine as an endpoint"""
+    def route(self, name: str = None):
+        """Used to register a coroutine as an endpoint when you have
+        access to an instance of :class:`.Server`.
+
+        Parameters
+        ----------
+        name: str
+            The endpoint name. If not provided the method name will be used.
+        """
 
         def decorator(func):
             if not name:
@@ -96,11 +129,19 @@ def decorator(func):
         return decorator
 
     def update_endpoints(self):
+        """Called internally to update the server's endpoints for cog routes."""
         self.endpoints = {**self.endpoints, **self.ROUTES}
 
         self.ROUTES = {}
 
-    async def handle_accept(self, request):
+    async def handle_accept(self, request: aiohttp.web.Request):
+        """Handles websocket requests from the client process.
+
+        Parameters
+        ----------
+        request: :class:`~aiohttp.web.Request`
+            The request made by the client, parsed by aiohttp.
+        """
         self.update_endpoints()
 
         websocket = aiohttp.web.WebSocketResponse()
@@ -159,8 +200,14 @@ async def handle_accept(self, request):
 
                     raise JSONEncodeError(error_response)
 
-    async def handle_multicast(self, request):
-        """Handle multicast requests"""
+    async def handle_multicast(self, request: aiohttp.web.Request):
+        """Handles multicasting websocket requests from the client.
+
+        Parameters
+        ----------
+        request: :class:`~aiohttp.web.Request`
+            The request made by the client, parsed by aiohttp.
+        """
         websocket = aiohttp.web.WebSocketResponse()
         await websocket.prepare(request)
 
@@ -189,7 +236,7 @@ async def __start(self, application, port):
         await site.start()
 
     def start(self):
-        """Start the IPC server"""
+        """Starts the IPC server."""
         self.bot.dispatch("ipc_ready")
 
         self._server = aiohttp.web.Application(loop=self.loop)

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,34 @@
+import re
+
+project = "discord-ext-ipc"
+copyright = "2021, Ext-Creators"
+author = "Ext-Creators"
+
+with open("../discord/ext/ipc/__init__.py") as stream:
+    release = version = re.search(
+        r"^__version__\s*=\s*[\'\"]([^\'\"]*)[\'\"]", stream.read(), re.MULTILINE
+    ).group(1)
+
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx_rtd_theme",
+    "sphinxcontrib_trio",
+]
+
+
+html_theme = "sphinx_rtd_theme"
+
+autodoc_typehints = "none"
+intersphinx_mapping = {
+    "aiohttp": ("https://docs.aiohttp.org/en/stable/", None),
+    "python": ("https://docs.python.org/3", None),
+    "discord": ("https://discordpy.readthedocs.io/en/latest", None),
+}
+
+highlight_language = "python3"
+master_doc = "index"
+pygments_style = "friendly"
+source_suffix = ".rst"

docs/index.rst

@@ -0,0 +1,21 @@
+Welcome to discord-ext-ipc's documentation!
+===========================================
+
+.. toctree::
+   :numbered:
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules/server.rst
+   modules/client.rst
+   modules/errors.rst
+   modules/examples.rst
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/modules/client.rst

@@ -0,0 +1,17 @@
+Client Connection
+=================
+
+The IPC client is very simple.
+It will simply connect to your server process and send JSON data.
+If you do not supply a port on initialisation, the client will connect to the multicast server
+(see the server section) and return the port from said server.
+If you do supply a port, it will connect to the server instantly.
+
+Requests are made by calling ``ipc.client.request(endpoint, **kwargs)``
+and will be sent to the server in the json format specified above.
+It will then wait for a response and return the data.
+
+.. currentmodule:: discord.ext.ipc.client
+
+.. autoclass:: Client
+    :members:

docs/modules/errors.rst

@@ -0,0 +1,14 @@
+IPC Errors
+==========
+
+.. currentmodule:: discord.ext.ipc.errors
+
+.. autoclass:: IPCError
+
+.. autoclass:: NoEndpointFoundError
+
+.. autoclass:: ServerConnectionRefusedError
+
+.. autoclass:: JSONEncodeError
+
+.. autoclass:: NotConnected