Improve doc

Makefile

@@ -69,7 +69,8 @@ check: lint flake coverage todo
 
 # DOC
 $(DOC_BUILD_DIR):
-	sphinx-apidoc --ext-viewcode -H $(NAME) -A $(AUTHOR) -V $(VERSION) -F -o $(DOC_DIR) $(SRC_DIR)/$(NAME)
+	sphinx-apidoc --extensions sphinxcontrib.napoleon -H $(NAME) -A $(AUTHOR) -V $(VERSION) -F -o $(DOC_DIR) $(SRC_DIR)/$(NAME)
+	grep -q autoclass_content $(DOC_DIR)/conf.py || printf '\nautoclass_content = "both"\nnapoleon_use_rtype = False' >> $(DOC_DIR)/conf.py
 
 html: $(DOC_BUILD_DIR)
 	$(SPHINX) -b html $(DOC_DIR) $(DOC_BUILD_DIR)

docs/index.rst

@@ -0,0 +1,8 @@
+Welcome to superdatabase3000's documentation!
+=============================================
+
+.. toctree::
+   :maxdepth: 4
+   :caption: Contents:
+
+   superdatabase3000

docs/superdatabase3000.rst

@@ -0,0 +1,16 @@
+superdatabase3000 package
+=========================
+
+
+DbServer
+------------------------------------------
+
+.. autoclass:: superdatabase3000.DbServer
+   :members:
+
+
+DbClient
+------------------------------------------
+
+.. autoclass:: superdatabase3000.DbClient
+   :members:

setup.py

@@ -170,6 +170,7 @@
             'coverage',
             'coveralls',
             'sphinx',
+            'sphinxcontrib-napoleon',
         ],
     },
 

src/superdatabase3000/hdf.py

@@ -38,13 +38,23 @@ def select(self, table, where=None, columns=None, start=None, stop=None):
         """
         Select rows (as a DataFrame) from the given 'table'.
 
-        start (int): row number to start selection (negative index allowed)
-        stop  (int): row number to stop selection (negative index allowed)
-        columns : a list of columns that will limit the return columns
-
-        Return None if something funky happens.
-        For the 'where' syntax, see:
-        https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#querying-a-table
+        Parameters
+        ----------
+        table : str
+            the name of the table to query
+        where : str
+            for the 'where' syntax, see:
+            https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#querying-a-table
+        columns : list
+            a list of columns that will limit the returned columns
+        start : int
+            row number to start selection (negative index allowed)
+        stop : int
+            row number to stop selection (negative index allowed)
+
+        Return
+        ------
+        The selected DataFrame, otherwise None if something funky happens.
         """
         if table not in self.store.keys():
             print(f"Hdf: select: can't find table {table}")
@@ -76,7 +86,17 @@ def insert(self, table, df):
         The table must always be sorted, so you should prefer inserting
         to the end (with growing indexes) if you need better performances.
 
-        Return False if the table doesn't exist or something funky happens.
+        Parameters
+        ----------
+        table : str
+            the name of the table to query
+        df : DataFrame
+            the DataFrame to insert in the database
+
+        Return
+        ------
+        bool
+            False if the table doesn't exist.
         """
         # update/'insert in the middle' are not currently supported,
         # so here's the deal:
@@ -117,9 +137,18 @@ def delete(self, table, where):
         """
         Drop the rows matching the 'where' close on the given 'table'.
 
-        Return False if the table doesn't exist.
-        For the 'where' syntax, see:
-        https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#querying-a-table
+        Parameters
+        ----------
+        table : str
+            the name of the table to query
+        where : str
+            for the 'where' syntax, see:
+            https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#querying-a-table
+
+        Return
+        ------
+        bool
+            False if the table doesn't exist.
         """
         try:
             self.store.remove(table, where)
@@ -132,7 +161,15 @@ def drop(self, table):
         """
         Drop the given 'table'.
 
-        Return False if the table doesn't exist.
+        Parameters
+        ----------
+        table : str
+            the name of the table to query
+
+        Return
+        ------
+        bool
+            False if the table doesn't exist.
         """
         try:
             del self.store[table]

src/superdatabase3000/socket.py

@@ -203,16 +203,15 @@ def poll_events(self, on_msg, timeout=0.5):
         Check for events on the server.
 
         This will handle:
-        - accepting/removing clients
-        - sending messages (the ones added to the queue with send_to)
-        - reading messages
-
-        If a message is successfully read from the socket, the 'on_msg' callback
-        will be called with 2 parameters: on_msg(socket_fd, msg)
-        - socket_fd (int):  the socket fd of the client
-        - msg (object):     the message received from the client
-        (You can use 'socket_fd' to answer to the client with send_to)
+            * accepting/removing clients
+            * sending messages (the ones added to the queue with send_to)
+            * reading messages
         """
+        # If a message is successfully read from the socket, the 'on_msg'
+        # callback will be called with 2 parameters: on_msg(socket_fd, msg)
+        # - socket_fd (int):  the socket fd of the client
+        # - msg (object):     the message received from the client
+        # (You can use 'socket_fd' to answer to the client with send_to)
         inputs = [c.sock for c in self.clients.values()] + [self.sock]
         rlist, wlist, xlist = select.select(
             inputs,

src/superdatabase3000/superdatabase3000.py

@@ -37,13 +37,14 @@ def __init__(self, sock_filename=None):
         Parameters
         ----------
         sock_filename : str
-        path to the DbServer socket
+            path to the DbServer socket (default: "/tmp/superdatabase3000.sock")
 
-        Examples
+        Example
         --------
-        # assuming a server is already launched
-        client = DbClient("/tmp/db.sock")
-        df = client.select("/toto")
+        Assuming a server is already launched
+
+        >>> client = DbClient("/tmp/db.sock")
+        >>> df = client.select("/toto")
         """
         self.socket = SocketClient(sock_filename)
 
@@ -68,22 +69,22 @@ def _query(self, method, args):
 
     @append_doc_of(HdfStoreManager.select)
     def select(self, table, where=None, columns=None, start=None, stop=None):
-        """This method is an interface to the hdf object on the server side."""
+        """"""
         return self._query("select", Args(table, where, columns, start, stop))
 
     @append_doc_of(HdfStoreManager.insert)
     def insert(self, table, df):
-        """This method is an interface to the hdf object on the server side."""
+        """"""
         return self._query("insert", Args(table, df=df))
 
     @append_doc_of(HdfStoreManager.delete)
     def delete(self, table, where):
-        """This method is an interface to the hdf object on the server side."""
+        """"""
         return self._query("delete", Args(table, where))
 
     @append_doc_of(HdfStoreManager.drop)
     def drop(self, table):
-        """This method is an interface to the hdf object on the server side."""
+        """"""
         return self._query("drop", Args(table))
 
 
@@ -95,18 +96,18 @@ def __init__(self, sock_filename=None, hdf_filename=None):
         Parameters
         ----------
         sock_filename : str
-        path to the DbServer socket
+            path to the DbServer socket (default: "/tmp/superdatabase3000.sock")
 
         hdf_filename : str
-        path to the DbServer socket
+            path to the DbServer hdf store (default: "~/.superdatabase3000.hdf")
 
-        Examples
+        Example
         --------
-        server = DbServer(
-            sock_filename="/tmp/db.sock",
-            hdf_filename="/tmp/db.h5"
-        )
-        server.read_loop()
+        >>> server = DbServer(
+        ...     sock_filename="/tmp/db.sock",
+        ...     hdf_filename="/tmp/db.h5"
+        ... )
+        >>> server.read_loop()
         """
         self.socket = SocketServer(sock_filename)
         self.hdf = HdfStoreManager(hdf_filename)