documentation improvements (#166)

* improve `SessionsBase` docs

* include viewcode Sphinx extension

* fix typo

* remove spaces

* add intro to openapi docs

* REST -> REST API

* add Piccolo Admin page to the docs

docs/source/conf.py

@@ -58,6 +58,10 @@
     "piccolo": ("https://piccolo-orm.readthedocs.io/en/latest/", None),
 }
 
+# -- Viewcode -------------------------------------------------------------
+
+extensions += ["sphinx.ext.viewcode"]
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

docs/source/crud/piccolo_crud.rst

@@ -3,8 +3,7 @@ PiccoloCRUD
 
 This creates an `ASGI <https://piccolo-orm.com/blog/introduction-to-asgi>`_ app,
 which exposes the usual `CRUD <https://en.wikipedia.org/wiki/Create,_read,_update_and_delete>`_
-methods on your Piccolo table, as well as some extras, via a `REST <https://en.wikipedia.org/wiki/Representational_state_transfer>`_
-API.
+methods on your Piccolo table, as well as some extras, via a `REST API <https://en.wikipedia.org/wiki/Representational_state_transfer>`_.
 
 -------------------------------------------------------------------------------
 

docs/source/csrf/usage.rst

@@ -170,7 +170,7 @@ endpoint, or just disable HTTP compression for your website.
 
 -------------------------------------------------------------------------------
 
-Module
+Source
 ------
 
 .. automodule:: piccolo_api.csrf.middleware

docs/source/index.rst

@@ -41,17 +41,23 @@ ASGI app, covering authentication, security, and more.
    ./advanced_auth/index
 
 .. toctree::
-   :caption: Contributing
+   :caption: Piccolo Admin
    :maxdepth: 1
 
-   ./contributing/index
+   ./piccolo_admin/index
 
 .. toctree::
    :caption: API Reference
    :maxdepth: 1
 
    ./api_reference/index
 
+.. toctree::
+   :caption: Contributing
+   :maxdepth: 1
+
+   ./contributing/index
+
 .. toctree::
    :caption: Changes
    :maxdepth: 1

docs/source/openapi/index.rst

@@ -1,6 +1,8 @@
 OpenAPI
 =======
 
+Piccolo API has great support for viewing OpenAPI schemas using SwaggerUI.
+
 Source
 ------
 

docs/source/piccolo_admin/index.rst

@@ -0,0 +1,14 @@
+Piccolo Admin
+=============
+
+`Piccolo Admin <https://piccolo-admin.readthedocs.io/en/latest/>`_ is a
+powerful web GUI which can be used to manage your data.
+
+It's similar to tools like Django Admin and WordPress, but uses a rich Vue.js
+front end, with a modern REST backend.
+
+Piccolo API powers Piccolo Admin. If you want to see how the technologies
+outlined here all work together, it's recommended to look at the Piccolo Admin
+source code.
+
+.. image:: ./images/piccolo_admin_screenshot.png

docs/source/rate_limiting/index.rst

@@ -17,6 +17,8 @@ Rate limiting is useful for certain public API endpoints. Examples are:
 RateLimitingMiddleware
 ----------------------
 
+Usage is simple - just wrap your ASGI app:
+
 .. code-block:: python
 
     from piccolo_api.rate_limiting.middleware import RateLimitingMiddleware
@@ -52,7 +54,7 @@ Stores the traffic data in memory. You can customise it as follows:
 
     app = RateLimitingMiddleware(
         my_asgi_app,
-        provider = InMemoryLimitProvider(
+        provider=InMemoryLimitProvider(
             limit=1000,
             timespan=300
         ),
@@ -68,7 +70,7 @@ specify this using the ``block_duration`` argument:
 
     app = RateLimitingMiddleware(
         my_asgi_app,
-        provider = InMemoryLimitProvider(
+        provider=InMemoryLimitProvider(
             limit=1000,
             timespan=300,
             block_duration=300  # Blocked for 5 minutes

docs/source/session_auth/tables.rst

@@ -63,3 +63,7 @@ SessionsBase
 .. currentmodule:: piccolo_api.session_auth.tables
 
 .. autoclass:: SessionsBase
+    :class-doc-from: class
+    :members:
+    :undoc-members:
+    :member-order: groupwise

piccolo_api/session_auth/tables.py

@@ -12,19 +12,24 @@
 
 class SessionsBase(Table, tablename="sessions"):
     """
-    Use this table, or inherit from it, to create for a session store.
-
-    We set a hard limit on the expiry date - it can keep on getting extended
-    up until this value, after which it's best to invalidate it, and either
-    require login again, or just create a new session token.
+    Use this table, or inherit from it, to create a session store.
     """
 
-    token = Varchar(length=100, null=False)
-    user_id = Integer(null=False)
-    expiry_date: t.Union[Timestamp, datetime] = Timestamp(
+    #: Stores the session token.
+    token: Varchar = Varchar(length=100, null=False)
+
+    #: Stores the user ID.
+    user_id: Integer = Integer(null=False)
+
+    #: Stores the expiry date for this session.
+    expiry_date: Timestamp = Timestamp(
         default=TimestampOffset(hours=1), null=False
     )
-    max_expiry_date: t.Union[Timestamp, datetime] = Timestamp(
+
+    #: We set a hard limit on the expiry date - it can keep on getting extended
+    #: up until this value, after which it's best to invalidate it, and either
+    #: require login again, or just create a new session token.
+    max_expiry_date: Timestamp = Timestamp(
         default=TimestampOffset(days=7), null=False
     )
 
@@ -35,6 +40,9 @@ async def create_session(
         expiry_date: t.Optional[datetime] = None,
         max_expiry_date: t.Optional[datetime] = None,
     ) -> SessionsBase:
+        """
+        Creates a session in the database.
+        """
         while True:
             token = secrets.token_urlsafe(nbytes=32)
             if not await cls.exists().where(cls.token == token).run():
@@ -54,20 +62,24 @@ async def create_session(
     def create_session_sync(
         cls, user_id: int, expiry_date: t.Optional[datetime] = None
     ) -> SessionsBase:
+        """
+        A sync equivalent of :meth:`create_session`.
+        """
         return run_sync(cls.create_session(user_id, expiry_date))
 
     @classmethod
     async def get_user_id(
         cls, token: str, increase_expiry: t.Optional[timedelta] = None
     ) -> t.Optional[int]:
         """
-        Returns the user_id if the given token is valid, otherwise None.
+        Returns the ``user_id`` if the given token is valid, otherwise
+        ``None``.
 
         :param increase_expiry:
-            If set, the `expiry_date` will be increased by the given amount
+            If set, the ``expiry_date`` will be increased by the given amount
             if it's close to expiring. If it has already expired, nothing
-            happens. The `max_expiry_date` remains the same, so there's a hard
-            limit on how long a session can be used for.
+            happens. The ``max_expiry_date`` remains the same, so there's a
+            hard limit on how long a session can be used for.
         """
         session: SessionsBase = (
             await cls.objects().where(cls.token == token).first().run()
@@ -92,12 +104,21 @@ async def get_user_id(
 
     @classmethod
     def get_user_id_sync(cls, token: str) -> t.Optional[int]:
+        """
+        A sync wrapper around :meth:`get_user_id`.
+        """
         return run_sync(cls.get_user_id(token))
 
     @classmethod
     async def remove_session(cls, token: str):
+        """
+        Deletes a matching session from the database.
+        """
         await cls.delete().where(cls.token == token).run()
 
     @classmethod
     def remove_session_sync(cls, token: str):
+        """
+        A sync wrapper around :meth:`remove_session`.
+        """
         return run_sync(cls.remove_session(token))