From 05026d525cc742fd3bb6c818f77ae0e715213e92 Mon Sep 17 00:00:00 2001
From: Stefano Pigozzi <me@steffo.eu>
Date: Sat, 17 Apr 2021 17:10:28 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=94=20Improve=20documentation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/source/conf.py          |  3 +--
 docs/source/index.rst        | 11 ++++++-----
 royalnet_console/__init__.py |  3 ++-
 royalnet_console/bullets.py  |  9 ++-------
 royalnet_console/pda.py      |  7 ++++++-
 5 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 54895570..3bbd8860 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -69,8 +69,7 @@ html_static_path = ['_static']
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3.8", None),
-    "sqlalchemy": ("https://docs.sqlalchemy.org/en/13/", None),
-    "async_property": ("https://async-property.readthedocs.io/en/latest/", None),
+    "royalnet": ("https://royalnet-6.readthedocs.io/en/latest", None)
 }
 
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 2b367982..9b2f6b42 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,14 +1,14 @@
-Royalnet 6
-==========
+Royalnet Console
+================
 
-Welcome to the documentation of Royalnet 6!
+Welcome to the documentation of Royalnet Console!
 
 
 Table of contents
 -----------------
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    autodoc/index
 
@@ -16,7 +16,8 @@ Table of contents
 Useful links
 ------------
 
-* `Royalnet on GitHub <https://github.com/Steffo99/royalnet-6>`_
+* `Royalnet Console on GitHub <https://github.com/Steffo99/royalnet-console>`_
+* `Documentation of Royalnet <https://royalnet-6.readthedocs.io/en/latest/>`_
 
 
 Indices and tables
diff --git a/royalnet_console/__init__.py b/royalnet_console/__init__.py
index cc84ca4c..288cfb14 100644
--- a/royalnet_console/__init__.py
+++ b/royalnet_console/__init__.py
@@ -1,5 +1,6 @@
 """
-A terminal-based implementation of the PDA class of the :mod:`royalnet.engineer` module.
+A terminal-based :class:`~royalnet.engineer.pda.implementations.base.PDAImplementation` of the :mod:`royalnet.engineer`
+module.
 """
 
 from .pda import *
diff --git a/royalnet_console/bullets.py b/royalnet_console/bullets.py
index a037b027..b2cd89ea 100644
--- a/royalnet_console/bullets.py
+++ b/royalnet_console/bullets.py
@@ -1,13 +1,10 @@
-# Module docstring
 """
 :class:`royalnet.engineer.proj.Bullet`\\ s for the :mod:`royalnet_console` frontend.
 """
 
-# Special imports
 from __future__ import annotations
 import royalnet.royaltyping as t
 
-# External imports
 import logging
 import datetime
 import os
@@ -17,7 +14,6 @@ import royalnet.engineer as engi
 import click
 import async_property as ap
 
-# Special global objects
 log = logging.getLogger(__name__)
 
 
@@ -26,7 +22,7 @@ async def console_message(*,
                           text: str = None,
                           files: t.List[t.BinaryIO] = None) -> engi.Message:
     """
-    Output a message to the console and return the resulting proj.
+    Output text to the console and return the corresponding :class:`~.engi.Message`.
 
     :param text: The text of the message.
     :param files: A :class:`list` of files to attach to the message.
@@ -41,7 +37,7 @@ async def console_message(*,
     log.debug("Sending message...")
     click.echo(text)
 
-    log.debug("Creating proj...")
+    log.debug("Creating message...")
     return ConsoleMessage(_text=text)
 
 
@@ -123,7 +119,6 @@ class ConsoleMessageReceived(engi.MessageReceived):
         return self._msg
 
 
-# Objects exported by this module
 __all__ = (
     "ConsoleUser",
     "ConsoleChannel",
diff --git a/royalnet_console/pda.py b/royalnet_console/pda.py
index 8110d5ed..51eb82ba 100644
--- a/royalnet_console/pda.py
+++ b/royalnet_console/pda.py
@@ -1,5 +1,5 @@
 """
-.. todo:: Document this.
+This module contains the :class:`.ConsolePDAImplementation`.
 """
 
 from __future__ import annotations
@@ -17,6 +17,11 @@ log = logging.getLogger(__name__)
 
 
 class ConsolePDAImplementation(engi.ConversationListImplementation):
+    """
+    A :class:`~.engi.ConversationListImplementation` which **blockingly** runs a small interactive chat in the command
+    line, and uses ``stdin`` e ``stdout`` to receive and send messages respectively.
+    """
+
     @property
     def namespace(self):
         return "console"