More polish to docs

README.rst

@@ -121,6 +121,10 @@ This project would not be possible without:
    libpg_query
 -  Postgres - …obviously
 
+The `logo image <https://thenounproject.com/term/argue/148100/>`__ used
+in the documentation is created by Gianni - Dolce Merda from the Noun
+Project.
+
 .. |build-status| image:: https://img.shields.io/travis/erik/squabble.svg?style=flat
     :alt: build status
     :target: https://travis-ci.org/erik/squabble

docs/conf.py

@@ -86,12 +86,21 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'description': 'An extensible linter for SQL.',
+    'logo': 'logo.png',
+    'logo_name': True,
+
+    'github_user': 'erik',
+    'github_repo': 'squabble',
+    'github_banner': True,
+    'github_button': False,
+}
 
 # 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 = []
+html_static_path = ['_static/']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/rules.rst

@@ -5,7 +5,9 @@ Squabble ships with several rules that are focused mostly on
 preventing unsafe schema migrations. To enable these rules,
 reference them in your ``.squabblerc`` configuration file.
 
-For example: ::
+For example:
+
+.. code-block:: json
 
   {
     "rules": {

squabble/config.py

@@ -39,8 +39,8 @@
 
     'full': {
         'description': ('Every rule that ships with squabble. The output will '
-                        'be noisy, but it\'s probably a good starting point to '
-                        'figure out which rules are useful.'),
+                        'be noisy, but it\'s probably a good starting point '
+                        'to figure out which rules are useful.'),
         'config': {
             'rules': {
                 'AddColumnDisallowConstraints': {
@@ -97,8 +97,8 @@ def discover_config_location():
 
 def _get_vcs_root():
     """
-    Return the path to the root of the Git repository for the current directory,
-    or empty string if not in a repository.
+    Return the path to the root of the Git repository for the current
+    directory, or empty string if not in a repository.
     """
     return subprocess.getoutput(
         'git rev-parse --show-toplevel 2>/dev/null || echo ""')

squabble/reporter.py

@@ -209,8 +209,8 @@ def json_reporter(issue, _file_contents):
 @reporter('sqlint')
 def sqlint_reporter(issue, file_contents):
     """
-    Format compatible with ``sqlint``, which is already integrated into Flycheck
-    and other editor linting frameworks.
+    Format compatible with ``sqlint``, which is already integrated into
+    Flycheck and other editor linting frameworks.
 
     Main difference is really just that there are only two severity
     levels: ``ERROR`` and ``WARNING``.

squabble/rules/require_concurrent_index.py

@@ -8,12 +8,12 @@
 
 class RequireConcurrentIndex(BaseRule):
     """
-    Require all new indexes to be created with `CONCURRENTLY` so they won't
+    Require all new indexes to be created with ``CONCURRENTLY`` so they won't
     block.
 
     By default, tables created in the same index are exempted, since they are
     known to be empty. This can be changed with the option
-    `"include_new_tables": true`
+    ``"include_new_tables": true``.
 
     Configuration: ::
 
@@ -33,6 +33,10 @@ class IndexNotConcurrent(Message):
 
         .. code-block:: sql
 
+           -- Don't do this
+           CREATE INDEX users_by_name ON users(name);
+
+           -- Try this instead
            CREATE INDEX CONCURRENTLY users_by_name ON users(name);
         """
         CODE = 1001

squabble/rules/require_primary_key.py

@@ -8,7 +8,7 @@
 
 class RequirePrimaryKey(BaseRule):
     """
-    Require that all new tables specify a PRIMARY KEY constraint.
+    Require that all new tables specify a ``PRIMARY KEY`` constraint.
 
     Configuration: ::
 
@@ -22,6 +22,17 @@ class MissingPrimaryKey(Message):
 
         If no single column will uniquely identify a row, creating a composite
         primary key is also possible.
+
+        .. code-block:: sql
+
+          CREATE TABLE users (email VARCHAR(128) PRIMARY KEY);
+
+          -- Also valid
+          CREATE TABLE users (
+            email VARCHAR(128),
+            -- ...
+            PRIMARY KEY(email)
+          );
         """
         CODE = 1002
         TEMPLATE = 'table "{tbl}" does not name a primary key'