roles: Add README.rst and lint

These role docs aren't exactly War and Peace, but I think longer term
as we fiddle about making things generic or not and moving them
around, we'll be better off having kept ourselves to writing
*something*.

Add terse README.rst files for all existing roles, and add simple
linter check to ensure new roles get them too.

Change-Id: Ibc836310fb8a45e12c2e31f112d92509ac350413

playbooks/roles/ansible-cron/README.rst

@@ -0,0 +1,21 @@
+Setup periodic runs of ``run_all.sh``, which runs playbooks against
+bridge.o.o and all hosts.
+
+**Role Variables**
+
+.. zuul:rolevar:: update_cron_interval
+
+   .. zuul:rolevar:: minute
+      :default: 15
+
+   .. zuul:rolevar:: hour
+      :default: *
+
+   .. zuul:rolevar:: day
+      :default: *
+
+   .. zuul:rolevar:: month
+      :default: *
+
+   .. zuul:rolevar:: weekday
+      :default: *

playbooks/roles/base-repos/README.rst

@@ -0,0 +1,5 @@
+Set basic repository sources
+
+**Role Variables**
+
+* None

playbooks/roles/base-server/README.rst

@@ -0,0 +1,5 @@
+Basic common server configuration
+
+**Role Variables**
+
+* None

playbooks/roles/disable-puppet-agent/README.rst

@@ -0,0 +1,5 @@
+Disable the puppet-agent service on a host
+
+**Role Variables**
+
+* None

playbooks/roles/install-ansible/README.rst

@@ -0,0 +1,5 @@
+Install and configure Ansible on a host via pip
+
+**Role Variables**
+
+* None

playbooks/roles/pip3/README.rst

@@ -0,0 +1,5 @@
+Install system packages for python3 pip and virtualenv
+
+**Role Variables**
+
+* None

playbooks/roles/root-keys/README.rst

@@ -0,0 +1,7 @@
+Write out root SSH private key
+
+**Role Variables**
+
+.. zuul:rolevar:: root_rsa_key
+
+   The root key to place in ``/root/.ssh/id_rsa``

playbooks/roles/set-hostname/README.rst

@@ -0,0 +1,8 @@
+Set hostname
+
+Remove ``cloud-init`` and statically set the hostname, hosts and
+mailname
+
+**Role Variables**
+
+* None

playbooks/roles/users/README.rst

@@ -0,0 +1,26 @@
+Configure users on a server
+
+Configure users on a server.  Users are given sudo access
+
+**Role Variables**
+
+.. zuul:rolevar:: all_users
+   :default: {}
+
+   Dictionary of all users.  Each user needs a ``uid``, ``gid`` and ``key``
+
+.. zuul:rolevar:: base_users
+   :default: []
+
+   Users to install on all hosts
+
+.. zuul:rolevar:: extra_users
+   :default: []
+
+   Extra users to install on a specific host or group
+
+.. zuul:rolevar:: disabled_users
+   :default: []
+
+   Users who should be removed from all hosts
+

tools/check_readme.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+# Trivial script run from tox -e linters to ensure roles have a
+# README.rst attached
+
+if ! [ -f $1/README.rst ]; then
+    echo "*** Missing role documentation: $1/README.rst"
+    exit 1
+fi

tox.ini

@@ -12,6 +12,8 @@ deps = -r{toxinidir}/test-requirements.txt
 [testenv:linters]
 whitelist_externals = bash
 commands =
+  bash -c "find playbooks/roles -maxdepth 1 -mindepth 1 -type d -print0 | \
+     xargs -t -n1 -0 {toxinidir}/tools/check_readme.sh"
   flake8
   {toxinidir}/tools/run-bashate.sh
   python3 {toxinidir}/tools/sorted_modules_env.py {toxinidir}/modules.env