Fixed a bunch of Sphinx warnings, refs #71

docs/conf.py

@@ -69,7 +69,7 @@ else:
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/configuration.md

@@ -1,4 +1,4 @@
-## Configuration
+# Configuration
 
 This tool uses [boto3](https://boto3.amazonaws.com/) under the hood which supports [a number of different ways](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html) of providing your AWS credentials.
 
@@ -8,7 +8,7 @@ You can set the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment vari
 
 You can also use the `--access-key=`, `--secret-key=`, `--session-token` and `--auth` options documented below.
 
-### Common command options
+## Common command options
 
 All of the `s3-credentials` commands also accept the following options for authenticating against AWS:
 

docs/contributing.md

@@ -1,4 +1,4 @@
-## Contributing
+# Contributing
 
 To contribute to this tool, first checkout the code. Then create a new virtual environment:
 
@@ -22,7 +22,7 @@ Any changes to the generated policies require an update to the README using [Cog
 
     cog -r README.md
 
-### Integration tests
+## Integration tests
 
 The main tests all use stubbed interfaces to AWS, so will not make any outbound API calls.
 

docs/create.md

@@ -1,4 +1,4 @@
-## Creating S3 credentials
+# Creating S3 credentials
 
 The `s3-credentials create` command is the core feature of this tool. Pass it one or more S3 bucket names, specify a policy (read-write, read-only or write-only) and it will return AWS credentials that can be used to access those buckets.
 
@@ -69,7 +69,7 @@ The `create` command has a number of options:
 - `--dry-run`: Output details of AWS changes that would have been made without applying them.
 - `--user-permissions-boundary`: Custom [permissions boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) to use for users created by this tool. The default is to restrict those users to only interacting with S3, taking the `--read-only` option into account. Use `none` to create users without any permissions boundary at all.
 
-### Changes that will be made to your AWS account
+## Changes that will be made to your AWS account
 
 How the tool works varies depending on if you are creating temporary or permanent credentials.
 
@@ -89,7 +89,7 @@ For temporary credentials:
 
 You can run the `create` command with the `--dry-run` option to see a summary of changes that would be applied, including details of generated policy documents, without actually applying those changes.
 
-### Using a custom policy
+## Using a custom policy
 
 The policy documents applied by this tool [are listed here](policy-documents.md).
 

docs/other-commands.md

@@ -1,6 +1,6 @@
-## Other commands
+# Other commands
 
-### policy
+## policy
 
 You can use the `s3-credentials policy` command to generate the JSON policy document that would be used without applying it. The command takes one or more required bucket names and a subset of the options available on the `create` command:
 
@@ -18,7 +18,7 @@ With none of these options it defaults to a read-write policy.
 ...
 ```
 
-### whoami
+## whoami
 
 To see which user you are authenticated as:
 
@@ -36,7 +36,7 @@ s3-credentials whoami --auth auth.json
     "Arn": "arn:aws:iam::462092780466:user/s3.read-only.static.niche-museums.com"
 }
 ```
-### list-users
+## list-users
 
 To see a list of all users that exist for your AWS account:
 
@@ -48,7 +48,7 @@ Add `--nl` to collapse these to single lines as valid newline-delimited JSON.
 
 Add `--csv` or `--tsv` to get back CSV or TSV data.
 
-### list-buckets
+## list-buckets
 
 Shows a list of all buckets in your AWS account.
 
@@ -146,7 +146,7 @@ A bucket with `public_access_block` might look like this:
 }
 ```
 
-### list-bucket
+## list-bucket
 
 To list the contents of a bucket, use `list-bucket`:
 
@@ -173,7 +173,7 @@ You can use the `--prefix myprefix/` option to list only keys that start with a
 
 The commmand accepts the same `--nl`, `--csv` and `--tsv` options as `list-users`.
 
-### list-user-policies
+## list-user-policies
 
 To see a list of inline policies belonging to users:
 
@@ -208,7 +208,7 @@ You can pass any number of usernames here. If you don't specify a username the t
 
     s3-credentials list-user-policies
 
-### list-roles
+## list-roles
 
 The `list-roles` command lists all of the roles available for the authenticated account.
 
@@ -325,7 +325,7 @@ Add `--nl` to collapse these to single lines as valid newline-delimited JSON.
 
 Add `--csv` or `--tsv` to get back CSV or TSV data.
 
-### delete-user
+## delete-user
 
 In trying out this tool it's possible you will create several different user accounts that you later decide to clean up.
 
@@ -342,7 +342,7 @@ User: s3.read-write.simonw-test-bucket-10
 ```
 You can pass it multiple usernames to delete multiple users at a time.
 
-### put-object
+## put-object
 
 You can upload a file to a key in an S3 bucket using `s3-credentials put-object`:
 
@@ -359,7 +359,7 @@ The `Content-Type` on the uploaded object will be automatically set based on the
     echo "<h1>Hello World</h1>" | \
       s3-credentials put-object my-bucket hello.html - --content-type "text/html"
 
-### get-object
+## get-object
 
 To download a file from a bucket use `s3-credentials get-object`:
 
@@ -370,7 +370,7 @@ This defaults to outputting the downloaded file to the terminal. You can instead
     s3-credentials get-object my-bucket hello.txt -o /path/to/hello.txt
 
 
-### set-cors-policy and get-cors-policy
+## set-cors-policy and get-cors-policy
 
 You can set the [CORS policy](https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors.html) for a bucket using the `set-cors-policy` command. S3 CORS policies are set at the bucket level - they cannot be set for individual items.
 

docs/policy-documents.md

@@ -1,8 +1,8 @@
-## Policy documents
+# Policy documents
 
 The IAM policies generated by this tool for a bucket called `my-s3-bucket` would look like this:
 
-### read-write (default)
+## read-write (default)
 
 <!-- [[[cog
 import cog, json
@@ -56,7 +56,7 @@ cog.out(
 ```
 <!-- [[[end]]] -->
 
-### --read-only
+## `--read-only`
 
 <!-- [[[cog
 result = runner.invoke(cli.cli, ["policy", "my-s3-bucket", "--read-only"])
@@ -96,7 +96,7 @@ cog.out(
 ```
 <!-- [[[end]]] -->
 
-### --write-only
+## `--write-only`
 
 <!-- [[[cog
 result = runner.invoke(cli.cli, ["policy", "my-s3-bucket", "--write-only"])
@@ -122,7 +122,7 @@ cog.out(
 ```
 <!-- [[[end]]] -->
 
-### --prefix my-prefix/
+## `--prefix my-prefix/`
 
 <!-- [[[cog
 result = runner.invoke(cli.cli, ["policy", "my-s3-bucket", "--prefix", "my-prefix/"])
@@ -187,7 +187,7 @@ cog.out(
 ```
 <!-- [[[end]]] -->
 
-### --prefix my-prefix/ --read-only
+## `--prefix my-prefix/ --read-only`
 
 <!-- [[[cog
 result = runner.invoke(cli.cli, ["policy", "my-s3-bucket", "--prefix", "my-prefix/", "--read-only"])
@@ -242,7 +242,7 @@ cog.out(
 ```
 <!-- [[[end]]] -->
 
-### --prefix my-prefix/ --write-only
+## `--prefix my-prefix/ --write-only`
 
 <!-- [[[cog
 result = runner.invoke(cli.cli, ["policy", "my-s3-bucket", "--prefix", "my-prefix/", "--write-only"])
@@ -270,7 +270,7 @@ cog.out(
 
 (public_bucket_policy)=
 
-### public bucket policy
+## public bucket policy
 
 Buckets created using the `--public` option will have the following bucket policy attached to them: