New docs theme (#136)

* user new docs theme

* remove whitespace

* configure intersphinx and autodoc

* fix formatting issues in CHANGES.rst

* fix typo in docs

* add missing section dividers to token auth docs

* fix RST lists

* add captions to homepage TOCs

* use autodoc on Hooks page

* update the session auth example

* improve docs on session auth tables

* add a docstring to `HookType`

* add links to Validators docstrings

* changed `session_login` and `session_logout` signatures

If a default value is a class type, it seems to break autodoc.

* added missing param tags to `CSRFMiddleware` docstring

* tidy up links to OWASP in docstring

* remove redundant comment in `CSPMiddleware`

* use autodoc on CSP page

* fix autodoc issue on `SessionsAuthBackend`

If the default value is a class type, it breaks autodoc. So it now defaults to `None`.

* fix autodoc issue with RateLimitingMiddleware

* add docstring to `RateLimitingMiddleware`

* add missing headers

* fix RST lists

* better explanation of creating custom rate limiting providers

* tidy up JWT docs

* improved docs for `FastAPIKwargs`

* fixing autodoc issues with `PiccoloCRUD`

* nicer RST links

* autodoc fixes for `FastAPIWrapper`

* fix linting errors

* Update serializers.rst

* improve fast api auth docs

* add fastapi screenshot

* improve fastapi examples - link to pymdb

docs/source/advanced_auth/index.rst

@@ -10,7 +10,7 @@ endpoints. An example is using :ref:`SessionAuth` for web users and
 
 You can do this using ``AuthenticationBackendJunction`` which wraps multiple
 ``AuthenticationBackend`` subclasses, and tries each in turn. If none of
-them successfully authenticate, than authentication fails.
+them successfully authenticate, then authentication fails.
 
 .. code-block:: python
 

docs/source/conf.py

@@ -35,25 +35,26 @@
 
 master_doc = "index"
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints"]
+extensions = []
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+# -- Autodoc -----------------------------------------------------------------
+
+extensions += ["sphinx.ext.autodoc"]
+autodoc_typehints = "signature"
+autodoc_typehints_format = "short"
+autoclass_content = "both"
+
+# -- Intersphinx -------------------------------------------------------------
+
+extensions += ["sphinx.ext.intersphinx"]
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "piccolo": ("https://piccolo-orm.readthedocs.io/en/latest/", None),
+}
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
-
-html_logo = "logo.png"
-html_theme_options = {"logo_only": True}
+html_theme = "piccolo_theme"

docs/source/contributing/index.rst

@@ -8,28 +8,28 @@ If you want to explore the interior of Piccolo API more deeply and help with the
 Get the tests running
 ---------------------
 
- * Create a new virtualenv
- * Clone the `Git repo <https://github.com/piccolo-orm/piccolo_api>`_
- * ``cd piccolo_api``
- * Install default dependencies: ``pip install -r requirements/requirements.txt``
- * Install development dependencies: ``pip install -r requirements/dev-requirements.txt``
- * Install test dependencies: ``pip install -r requirements/test-requirements.txt``
- * Setup Postgres
- * Run the automated code linting/formatting tools: ``./scripts/lint.sh``
- * Run the test suite with Postgres: ``./scripts/test-postgres.sh``
- * Run the test suite with Sqlite: ``./scripts/test-sqlite.sh``
+* Create a new virtualenv
+* Clone the `Git repo <https://github.com/piccolo-orm/piccolo_api>`_
+* ``cd piccolo_api``
+* Install default dependencies: ``pip install -r requirements/requirements.txt``
+* Install development dependencies: ``pip install -r requirements/dev-requirements.txt``
+* Install test dependencies: ``pip install -r requirements/test-requirements.txt``
+* Setup Postgres
+* Run the automated code linting/formatting tools: ``./scripts/lint.sh``
+* Run the test suite with Postgres: ``./scripts/test-postgres.sh``
+* Run the test suite with Sqlite: ``./scripts/test-sqlite.sh``
 
 
 Contributing to the docs
 ------------------------
 
 The docs are written using Sphinx. To get them running locally:
 
- * Install the requirements: ``pip install -r requirements/doc-requirements.txt``
- * ``cd docs``
- * Do an initial build of the docs: ``make html``
- * Serve the docs: ``python serve_docs.py``
- * The docs will auto rebuild as you make changes.
+* Install the requirements: ``pip install -r requirements/doc-requirements.txt``
+* ``cd docs``
+* Do an initial build of the docs: ``make html``
+* Serve the docs: ``python serve_docs.py``
+* The docs will auto rebuild as you make changes.
 
 Code style
 ----------

docs/source/crud/hooks.rst

@@ -1,12 +1,16 @@
 Hooks
 =====
 
-Hooks allow executing custom code as part of processing a CRUD request. You can use this to validate data, call another custom API, place messages on queues and many other things.
+Hooks allow executing custom code as part of processing a CRUD request. You can
+use this to validate data, call another custom API, place messages on queues
+and many other things.
+
+-------------------------------------------------------------------------------
 
 Enabling a hook
 ---------------
 
-Define a method, and register it with ``PiccoloCRUD``:
+Define a method, and register it with :class:`PiccoloCRUD <piccolo_api.crud.endpoints.PiccoloCRUD>`:
 
 .. code-block:: python
 
@@ -15,19 +19,23 @@ Define a method, and register it with ``PiccoloCRUD``:
 
     from movies.tables import Movie
 
+
     # set movie rating to 10 before saving
     async def set_movie_rating_10(row: Movie):
         row.rating = 10
         return row
 
+
     # set movie rating to 20 before saving
     async def set_movie_rating_10(row: Movie):
         row.rating = 20
         return row
 
+
     async def pre_delete(row_id):
         pass
 
+
     # Register one or multiple hooks
     app = PiccoloCRUD(
         table=Movie,
@@ -42,10 +50,14 @@ Define a method, and register it with ``PiccoloCRUD``:
 You can specify multiple hooks (also per ``hook_type``). Hooks are executed in order.
 You can use either async or regular functions.
 
+-------------------------------------------------------------------------------
+
 Hook types
 ----------
 
-There are different hook types, and each type takes a slightly different set of inputs.
+There are different hook types, and each type takes a slightly different set of
+inputs.
+
 It's also important to return the expected data from your hook.
 
 pre_save
@@ -69,37 +81,71 @@ It takes a single parameter, ``row``, and should return the same:
 pre_patch
 ~~~~~~~~~
 
-This hook runs during PATCH requests, prior to changing the specified row in the database.
-It takes two parameters, ``row_id`` which is the id of the row to be changed, and ``values`` which is a dictionary of incoming values.
+This hook runs during PATCH requests, prior to changing the specified row in
+the database.
+
+It takes two parameters, ``row_id`` which is the id of the row to be changed,
+and ``values`` which is a dictionary of incoming values.
+
 Each function must return a dictionary which represent the data to be modified.
 
 .. code-block:: python
 
     async def reset_name(row_id: int, values: dict):
-        current_db_row = await Movie.objects().get(Movie.id==row_id).run()
+        current_db_row = await Movie.objects().get(Movie.id==row_id)
         if values.get("name"):
             values["name"] = values["name"].replace(" ", "")
         return values
 
-    app = PiccoloCRUD(table=Movie, read_only=False, hooks=[
-        Hook(hook_type=HookType.pre_patch, callable=reset_name)
+
+    app = PiccoloCRUD(
+        table=Movie,
+        read_only=False,
+        hooks=[
+            Hook(hook_type=HookType.pre_patch, callable=reset_name)
         ]
     )
 
 
 pre_delete
 ~~~~~~~~~~
 
-This hook runs during DELETE requests, prior to deleting the specified row in the database.
+This hook runs during DELETE requests, prior to deleting the specified row in
+the database.
+
 It takes one parameter, ``row_id`` which is the id of the row to be deleted.
+
 ``pre_delete`` hooks should not return data.
 
 .. code-block:: python
 
     async def pre_delete(row_id: int):
         pass
 
-    app = PiccoloCRUD(table=Movie, read_only=False, hooks=[
-        Hook(hook_type=HookType.pre_delete, callable=pre_delete)
+
+    app = PiccoloCRUD(
+        table=Movie,
+        read_only=False,
+        hooks=[
+            Hook(hook_type=HookType.pre_delete, callable=pre_delete)
         ]
     )
+
+-------------------------------------------------------------------------------
+
+Source
+------
+
+.. currentmodule:: piccolo_api.crud.hooks
+
+HookType
+~~~~~~~~
+
+.. autoclass:: HookType
+    :members:
+    :undoc-members:
+
+Hook
+~~~~
+
+.. autoclass:: Hook

docs/source/crud/piccolo_crud.rst

@@ -130,11 +130,11 @@ Operators
 
 As shown above you can specify which operator to use. The allowed operators are:
 
- * lt: Less Than
- * lte: Less Equal Than
- * gt: Greater Than
- * gte: Greater Equal Than
- * e: Equal (default)
+* lt: Less Than
+* lte: Less Equal Than
+* gt: Greater Than
+* gte: Greater Equal Than
+* e: Equal (default)
 
 To specify which operator to use, pass a query parameter like ``field__operator=operator_name``.
 For example ``duration__operator=gte``.
@@ -151,10 +151,10 @@ Match type
 When querying text fields (like ``Varchar`` and ``Text``), you can specify the
 kind of match you're looking for.
 
- * contains
- * exact
- * starts
- * ends
+* contains
+* exact
+* starts
+* ends
 
 To specify which match type to use, pass a query parameter like ``field__match=match_type``.
 For example ``name__match=starts``.
@@ -317,6 +317,14 @@ Example usage:
 Source
 ------
 
+PiccoloCRUD
+~~~~~~~~~~~
+
 .. currentmodule:: piccolo_api.crud.endpoints
 
 .. autoclass:: PiccoloCRUD
+
+Validators
+~~~~~~~~~~
+
+.. autoclass:: Validators

docs/source/crud/serializers.rst

@@ -1,13 +1,10 @@
 Serializers
 ===========
 
-``PiccoloCRUD`` uses ``create_pydantic_model`` to serialize and deserialize data.
+:class:`PiccoloCRUD<piccolo_api.crud.endpoints.PiccoloCRUD>` uses :func:`create_pydantic_model <piccolo.utils.pydantic.create_pydantic_model>`
+internally to serialize and deserialize data.
 
-When using ``PiccoloCRUD``, you don't have to worry about serialisation because ``PiccoloCRUD`` 
-internally uses ``create_pydantic_model`` to create a `Pydantic model <https://pydantic-docs.helpmanual.io/usage/models/>`_
-from a Piccolo ``Table``. However, ``create_pydantic_model`` is very useful when
-integrating Piccolo with a framework such as `FastAPI <https://github.com/tiangolo/fastapi>`_,
-which also uses `Pydantic <https://github.com/samuelcolvin/pydantic>`_ for serialisation.
-
-See the `create_pydantic_model docs <https://piccolo-orm.readthedocs.io/en/latest/piccolo/serialization/index.html>`_
-for more details.
+:func:`create_pydantic_model <piccolo.utils.pydantic.create_pydantic_model>` is
+very useful when integrating Piccolo with a framework such as `FastAPI <https://github.com/tiangolo/fastapi>`_,
+which also uses `Pydantic <https://github.com/samuelcolvin/pydantic>`_ for
+serialisation. It automatically creates Pydantic models for you.

docs/source/csp/index.rst

@@ -5,6 +5,8 @@ CSP (Content Security Policy) middleware signals to a browser to only execute
 scripts which have come from the same domain. This provides some defence
 against cross site scripting.
 
+-------------------------------------------------------------------------------
+
 Usage
 -----
 
@@ -13,3 +15,20 @@ Usage
     from piccolo_api.csp.middleware import CSPMiddleware
 
     app = CSPMiddleware(my_asgi_app)
+
+-------------------------------------------------------------------------------
+
+Source
+------
+
+.. currentmodule:: piccolo_api.csp.middleware
+
+CSPConfig
+~~~~~~~~~
+
+.. autoclass:: CSPConfig
+
+CSPMiddleware
+~~~~~~~~~~~~~
+
+.. autoclass:: CSPMiddleware