Merge pull request piccolo-orm#49 from piccolo-orm/documentation_improvements

Documentation improvements

Author: dantownsend

docs/src/piccolo/features/syntax.rst

@@ -15,12 +15,11 @@ For example:
 Get the SQL at any time
 -----------------------
 
-At any time you can access the __str__ method of a query, to see the
+At any time you can access the ``__str__`` method of a query, to see the
 underlying SQL - making the ORM feel less magic.
 
 .. code-block:: python
 
-    query = Band.select(Band.name).where(Band.popularity >= 100)
-
-    print(query)
+    >>> query = Band.select(Band.name).where(Band.popularity >= 100)
+    >>> print(query)
     'SELECT name from band where popularity > 100'

docs/src/piccolo/getting_started/database_support.rst

@@ -3,8 +3,9 @@
 Database Support
 ================
 
-Postgres is the primary database which Piccolo was designed for.
+`Postgres <https://www.postgresql.org/>`_ is the primary database which Piccolo
+was designed for.
 
-Limited SQLite support is available, mostly to enable tooling like the
-playground. Postgres is the only database we recommend for use in production
-with Piccolo.
+Limited `SQLite <https://www.sqlite.org/index.html>`_ support is available,
+mostly to enable tooling like the :ref:`playground <Playground>`. Postgres is the only database we
+recommend for use in production with Piccolo.

docs/src/piccolo/getting_started/what_is_piccolo.rst

@@ -9,5 +9,6 @@ Some of it's stand out features are:
 * A builtin playground, which makes learning a breeze - see :ref:`Playground`.
 * Works great with `iPython <https://ipython.org/>`_ and
   `VSCode <https://code.visualstudio.com/>`_ - see :ref:`tab_completion`.
-* Batteries included - a User model, authentication, migrations, an admin,
+* Batteries included - a :ref:`User model and authentication <Authentication>`, :ref:`migrations <migrations>`, an :ref:`admin <ecosystem>`,
   and more.
+* Templates for creating your own :ref:`ASGI web app <ASGICommand>`.

docs/src/piccolo/query_types/create_table.rst

@@ -11,3 +11,11 @@ This creates the table and columns in the database.
 
     >>> Band.create_table().run_sync()
     []
+
+
+To prevent an error from being raised if the table already exists:
+
+.. code-block:: python
+
+    >>> Band.create_table(if_not_exists=True).run_sync()
+    []

docs/src/piccolo/query_types/django_comparison.rst

@@ -114,4 +114,4 @@ Database Settings
 -----------------
 
 In Django you configure your database in ``settings.py``. With Piccolo, you
-definte an ``Engine`` in ``piccolo_conf.py``. See :ref:`Engines`.
+define an ``Engine`` in ``piccolo_conf.py``. See :ref:`Engines`.

docs/src/piccolo/query_types/select.rst

@@ -50,11 +50,9 @@ One of the most powerful things about select is it's support for joins.
 
 .. code-block:: python
 
-    b = Band
-    b.select(
-        b.name,
-        b.manager.name
-    ).run_sync()
+    >>> b = Band
+    >>> b.select(b.name, b.manager.name).run_sync()
+    [{'name': 'Pythonistas', 'manager.name': 'Guido'}, {'name': 'Rustaceans', 'manager.name': 'Graydon'}]
 
 
 The joins can go several layers deep.
@@ -163,7 +161,7 @@ To return the data as a JSON string:
 Piccolo can use `orjson <https://github.com/ijl/orjson>`_ for JSON serialisation,
 which is blazing fast, and can handle most Python types, including dates,
 datetimes, and UUIDs. To install Piccolo with orjson support use
-`pip install piccolo[orjson]`.
+``pip install piccolo[orjson]``.
 
 where
 ~~~~~

docs/src/piccolo/query_types/transactions.rst

@@ -11,7 +11,7 @@ inbetween state.
 Atomic
 ------
 
-This is useful when you want to programitcally add some queries to the
+This is useful when you want to programmatically add some queries to the
 transaction before running it.
 
 .. code-block:: python