docs(*): provide docstrings throughout

DOCUMENT ALL THE THINGS!!!!!! Should provide docstrings for all code, so we can get all with Sphinx.

pyprql/cli/PRQLCompleter.py

@@ -10,7 +10,23 @@
 
 
 class PRQLCompleter(Completer):
-    """Prompt_toolkit completion engine for PyPRQL CLI."""
+    """Prompt_toolkit completion engine for PyPRQL CLI.
+
+    This provides some of the root completion material.
+    Inherits from  prompt_toolkit's ``Completer`` class,
+    and overrides methods to achieve desired functionality.
+
+    Parameters
+    ----------
+    table_names : List[str]
+        List of available tables.
+    column_names : List[str]
+        List of available columns.
+    column_map : Dict[str, List[str]]
+        A column-to-table map.
+    prql_keywords : List[str]
+        list of PRQL keywords.
+    """
 
     @enforce_types
     def __init__(
@@ -20,23 +36,6 @@ def __init__(
         column_map: Dict[str, List[str]],
         prql_keywords: List[str],
     ) -> None:
-        """Initialise a completer instance.
-
-        This provides some of the root completion material.
-        Inherits from  prompt_toolkit's ``Completer`` class,
-        and overrides methods to achieve desired functionality.
-
-        Parameters
-        ----------
-        table_names : List[str]
-            List of available tables.
-        column_names : List[str]
-            List of available columns.
-        column_map : Dict[str, List[str]]
-            A column-to-table map.
-        prql_keywords : List[str]
-            list of PRQL keywords.
-        """
         self.table_names = table_names
         self.column_names = column_names
         self.column_map = column_map
@@ -49,6 +48,18 @@ def __init__(
 
     @enforce_types
     def parse_prql(self, text: str) -> Optional[prql.Root]:
+        """Parse a PRQL string to AST.
+
+        Parameters
+        ----------
+        text : str
+            The PRQL query to parse.
+
+        Returns
+        -------
+        Optional[prql.Root]
+            The parsed AST tree.
+        """
         ast = prql.parse(text)
         return ast
 
@@ -197,6 +208,22 @@ def get_completions(
 
     @enforce_types
     def get_table_aliases(self, full_text: str) -> Optional[Dict]:
+        """Retrieve aliases for the used tables.
+        
+        Parse the given PRQL query.
+        Then, iterates through all ``join`` and ``from`` statements
+        to retrieve the aliases of all used tables.
+
+        Parameters
+        ----------
+        full_text : str
+            The PRQL query to parse.
+
+        Returns
+        -------
+        Optional[Dict]
+            All used table aliases.
+        """
         try:
             ret = {}
             root = self.parse_prql(full_text)
@@ -217,6 +244,18 @@ def get_table_aliases(self, full_text: str) -> Optional[Dict]:
 
     @enforce_types
     def get_from_table(self, full_text: str) -> Optional[str]:
+        """Retrieve the ``from`` statement from a PRQL query.
+
+        Parameters
+        ----------
+        full_text : str
+            The PRQL query to parse.
+
+        Returns
+        -------
+        Optional[str]
+            The ``from`` clause in the given query.
+        """
         try:
             root = self.parse_prql(full_text)
             return str(root.get_from())

pyprql/cli/PRQLLexer.py

@@ -15,10 +15,16 @@
 
 
 class PRQLLexer(RegexLexer):
-    """
-    For PRQL.
+    """Provide a custon PRQL Pygments Lexer.
+
+    Inherits from ``pygments.lexer.RegexLexer``
 
-    .. versionadded:: 1
+    Notes
+    -----
+    The properties provided here mirror those defined
+    in the standard RegexLexer. For full documentation,
+    the interested user is directed to the Pygments
+    `website <https://pygments.org/docs/lexerdevelopment/>_.
     """
 
     name = "PRQL"

pyprql/cli/PRQLStyle.py

@@ -21,9 +21,8 @@ class PRQLStyle(Style):
     Inherits from pygments ``Style``,
     overriding values to create our colour scheme.
     The various style attributes are self-descriptive,
-    and thoroughly documented on the `pygments`_ page.
-
-    .. _pygments: https://pygments.org/docs/styledevelopment/
+    and thoroughly documented on the pygments
+    `website <https://pygments.org/docs/styledevelopment/>`_.
     """
 
     background_color = "#202020"

pyprql/cli/cli.py

@@ -61,19 +61,22 @@ class CLI:
 
     Note
     ----
-    If ``connect_str`` is a path to a csv file,
-    then an in-memory sqlite database is created,
-    and the contents of the csv dumped to this database.
+    This additionally defines a number of default parameter values,
+    generally used to control state of the connection and prompt.
+
+    **has_one_blank** : bool, default False
+
+    **prompt_test** : str, default "PRQL>"
+
+    **command** : str, default ""
+
+    **sql_mode** : bool, default False
 
     Note
     ----
-        This additionally defines a number of default parameter values,
-        generally used to control state of the connection and prompt.
-
-        has_one_blank : bool, default False
-        prompt_test : str, default "PRQL>"
-        command : str, default ""
-        sql_mode : bool, default False
+    If ``connect_str`` is a path to a csv file,
+    then an in-memory sqlite database is created,
+    and the contents of the csv dumped to this database.
 
     Note
     ----