Policy examples in README using Cog, refs #36

.github/workflows/test.yml

@@ -27,4 +27,6 @@ jobs:
     - name: Run tests
       run: |
         pytest
-
+    - name: Check if README is up-to-date
+      run: |
+        cog --check README.md

README.md

@@ -395,6 +395,130 @@ https://console.aws.amazon.com/s3/home
 
 The management interface for an individual bucket is at `https://console.aws.amazon.com/s3/buckets/NAME-OF-BUCKET`
 
+## Policy documents
+
+The IAM policies generated by this tool for a bucket called `my-s3-bucket` would look like this:
+
+### read-write (default)
+
+<!-- [[[cog
+import cog, json
+from s3_credentials import cli
+from click.testing import CliRunner
+runner = CliRunner()
+result = runner.invoke(cli.cli, ["policy", "my-s3-bucket"])
+cog.out(
+    "```\n{}\n```".format(json.dumps(json.loads(result.output), indent=2))
+)
+]]] -->
+```
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:ListBucket",
+        "s3:GetBucketLocation"
+      ],
+      "Resource": [
+        "arn:aws:s3:::my-s3-bucket"
+      ]
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:GetObject",
+        "s3:GetObjectAcl",
+        "s3:GetObjectLegalHold",
+        "s3:GetObjectRetention",
+        "s3:GetObjectTagging"
+      ],
+      "Resource": [
+        "arn:aws:s3:::my-s3-bucket/*"
+      ]
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:PutObject",
+        "s3:DeleteObject"
+      ],
+      "Resource": [
+        "arn:aws:s3:::my-s3-bucket/*"
+      ]
+    }
+  ]
+}
+```
+<!-- [[[end]]] -->
+
+### --read-only
+
+<!-- [[[cog
+result = runner.invoke(cli.cli, ["policy", "my-s3-bucket", "--read-only"])
+cog.out(
+    "```\n{}\n```".format(json.dumps(json.loads(result.output), indent=2))
+)
+]]] -->
+```
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:ListBucket",
+        "s3:GetBucketLocation"
+      ],
+      "Resource": [
+        "arn:aws:s3:::my-s3-bucket"
+      ]
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:GetObject",
+        "s3:GetObjectAcl",
+        "s3:GetObjectLegalHold",
+        "s3:GetObjectRetention",
+        "s3:GetObjectTagging"
+      ],
+      "Resource": [
+        "arn:aws:s3:::my-s3-bucket/*"
+      ]
+    }
+  ]
+}
+```
+<!-- [[[end]]] -->
+
+### --write-only
+
+<!-- [[[cog
+result = runner.invoke(cli.cli, ["policy", "my-s3-bucket", "--write-only"])
+cog.out(
+    "```\n{}\n```".format(json.dumps(json.loads(result.output), indent=2))
+)
+]]] -->
+```
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:PutObject"
+      ],
+      "Resource": [
+        "arn:aws:s3:::my-s3-bucket/*"
+      ]
+    }
+  ]
+}
+```
+<!-- [[[end]]] -->
+
 ## Development
 
 To contribute to this tool, first checkout the code. Then create a new virtual environment:
@@ -415,6 +539,10 @@ To run the tests:
 
     pytest
 
+Any changes to the generated policies require an update to the README using [Cog](https://github.com/nedbat/cog):
+
+    cog -r README.md
+
 ### Integration tests
 
 The main tests all use stubbed interfaces to AWS, so will not make any outbound API calls.

setup.py

@@ -32,6 +32,6 @@ setup(
         s3-credentials=s3_credentials.cli:cli
     """,
     install_requires=["click", "boto3"],
-    extras_require={"test": ["pytest", "pytest-mock"]},
+    extras_require={"test": ["pytest", "pytest-mock", "cogapp"]},
     python_requires=">=3.6",
 )