improved docs for user app, and projects

Author: dantownsend

docs/src/piccolo/authentication/baseuser.rst

@@ -3,48 +3,81 @@
 BaseUser
 ========
 
-Inherit from ``BaseUser`` to create your own User table.
+``BaseUser`` is a ``Table`` you can use to store and authenticate your users.
 
-.. code-block:: python
+-------------------------------------------------------------------------------
 
-    from piccolo.apps.user.tables import BaseUser
+Creating the Table
+------------------
+
+Run the migrations:
+
+.. code-block:: bash
+
+    piccolo migrations forwards user
+
+-------------------------------------------------------------------------------
+
+Commands
+--------
+
+The app comes with some useful commands.
+
+user create
+~~~~~~~~~~~
 
+Create a new user.
 
-    class User(BaseUser, tablename="custom_user"):
-        pass
+.. code-block:: bash
 
-.. hint:: A table name of `user` isn't allowed since it clashes with a keyword in Postgres - so override the ``tablename``, if you choose to name your class ``User``.
+    piccolo user create
+
+user change_password
+~~~~~~~~~~~~~~~~~~~~
+
+Change a user's password.
+
+.. code-block:: bash
+
+    piccolo user change_password
+
+-------------------------------------------------------------------------------
+
+Within your code
+----------------
 
 login
------
+~~~~~
 
-To login a user, do the following:
+To check a user's credentials, do the following:
 
 .. code-block:: python
 
+    from piccolo.apps.user.tables import BaseUser
+
     # From within a coroutine:
-    await User.login(username="bob", password="abc123")
-    >>> 1
+    >>> await BaseUser.login(username="bob", password="abc123")
+    1
 
     # When not in an event loop:
-    User.login_sync(username="bob", password="abc123")
-    >>> 1
+    >>> BaseUser.login_sync(username="bob", password="abc123")
+    1
 
 If the login is successful, the user's id is returned, otherwise ``None`` is
 returned.
 
 update_password / update_password_sync
---------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To change a user's password:
 
 .. code-block:: python
 
     # From within a coroutine:
-    await User.update_password(username="bob", password="abc123")
+    await BaseUser.update_password(username="bob", password="abc123")
 
     # When not in an event loop:
-    User.update_password_sync(username="bob", password="abc123")
+    BaseUser.update_password_sync(username="bob", password="abc123")
 
 .. warning:: Don't use bulk updates for passwords - use ``update_password`` /
    ``update_password_sync``, and they'll correctly hash the password.

docs/src/piccolo/authentication/index.rst

@@ -3,7 +3,20 @@
 Authentication
 ==============
 
-Piccolo ships with some basic authentication support out of the box.
+Piccolo ships with some authentication support out of the box.
+
+-------------------------------------------------------------------------------
+
+Registering the app
+-------------------
+
+Make sure ``'piccolo.apps.user.piccolo_conf'`` is in your ``AppRegistry`` (see
+:ref:`PiccoloProjects`).
+
+-------------------------------------------------------------------------------
+
+Tables
+------
 
 .. toctree::
     :maxdepth: 1

docs/src/piccolo/projects_and_apps/index.rst

@@ -3,6 +3,9 @@
 Projects and Apps
 =================
 
+By using Piccolo projects and apps, you can build a larger, more modular,
+application.
+
 .. toctree::
     :maxdepth: 1
 

docs/src/piccolo/projects_and_apps/piccolo_projects.rst

@@ -5,13 +5,67 @@ Piccolo Projects
 
 A Piccolo project is a collection of apps.
 
+-------------------------------------------------------------------------------
+
+piccolo_conf.py
+---------------
+
 A project requires a `piccolo_conf.py` file. To create this file, use the following command:
 
 .. code-block:: bash
 
     piccolo project new
 
-The piccolo_conf file serves two important purposes:
+The file serves two important purposes:
 
  * Contains your database settings
  * Is used for registering :ref:`PiccoloApps`.
+
+-------------------------------------------------------------------------------
+
+Example
+-------
+
+Here's an example:
+
+.. code-block:: python
+
+    from piccolo.engine.postgres import PostgresEngine
+
+
+    from piccolo.conf.apps import AppRegistry
+
+
+    DB = PostgresEngine(
+        config={
+            "database": "piccolo_project",
+            "user": "postgres",
+            "password": "",
+            "host": "localhost",
+            "port": 5432,
+        }
+    )
+
+
+    APP_REGISTRY = AppRegistry(
+        apps=["home.piccolo_app", "piccolo_admin.piccolo_app"]
+    )
+
+-------------------------------------------------------------------------------
+
+DB
+--
+
+The DB setting is an ``Engine`` instance. To learn more Engines, see
+:ref:`Engines`.
+
+-------------------------------------------------------------------------------
+
+APP_REGISTRY
+------------
+
+The ``APP_REGISTRY`` setting is an ``AppRegistry`` instance.
+
+.. currentmodule:: piccolo.conf.apps
+
+.. autoclass:: AppRegistry

piccolo/conf/apps.py

@@ -72,6 +72,14 @@ def register_table(self, table_class: t.Type[Table]):
 
 @dataclass
 class AppRegistry:
+    """
+    Records all of the Piccolo apps in your project.
+
+    :param apps:
+        A list of paths to Piccolo apps, e.g. ['blog.piccolo_app']
+
+    """
+
     apps: t.List[str] = field(default_factory=list)
 
     def __post_init__(self):