[PR #1001/35dddca backport] [stable-4] Publish push-based docsite to …

…GitHub pages (#1003)

[PR #1001/35dddca backport] [stable-4] Publish push-based docsite to GitHub pages

SUMMARY
Manual backport of #1001
Adds a GitHub action to automatically publish the collection documentation to GitHub pages Additional things this enables (via docsite/links.yml):

"Edit on GitHub" button automatically added to docs pages
Communications links to the matrix and IRC rooms

ISSUE TYPE

Docs Pull Request

COMPONENT NAME
docs/
README.md
.github/workflows/
ADDITIONAL INFORMATION

Reviewed-by: Alina Buzachis <None>

.github/workflows/docs-pr.yml

@@ -6,6 +6,9 @@ on:
   pull_request_target:
     types: [opened, synchronize, reopened, closed]
 
+env:
+  GHP_BASE_URL: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}
+
 jobs:
   validate-docs:
     permissions:
@@ -54,6 +57,9 @@ jobs:
             The docsite for **this PR** is available for download as an artifact from this run:
             ${{ needs.build-docs.outputs.artifact-url }}
 
+            You can compare to the docs for the `main` branch here:
+            ${{ env.GHP_BASE_URL }}/branch/main
+
             File changes:
 
             ${{ needs.build-docs.outputs.diff-files-rendered }}

.github/workflows/docs-push.yml

@@ -0,0 +1,36 @@
+name: Collection Docs
+concurrency:
+  group: docs-push-${{ github.sha }}
+  cancel-in-progress: true
+on:
+  push:
+    branches:
+      - main
+      - stable-*
+    tags:
+      - '*'
+  schedule:
+    - cron: '0 12 * * *'
+
+jobs:
+  build-docs:
+    permissions:
+      contents: read
+    name: Build Ansible Docs
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-push.yml@main
+    with:
+      init-lenient: false
+      init-fail-on-error: true
+
+  publish-docs-gh-pages:
+    # use to prevent running on forks
+    if: github.repository == 'ansible-collections/amazon.aws'
+    permissions:
+      contents: write
+    needs: [build-docs]
+    name: Publish Ansible Docs
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-publish-gh-pages.yml@main
+    with:
+      artifact-name: ${{ needs.build-docs.outputs.artifact-name }}
+    secrets:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -33,65 +33,8 @@ Version 4.0.0 of this collection supports `boto3 >= 1.17.0` and `botocore >= 1.2
 All support for the original AWS SDK `boto` was removed in release 4.0.0.
 
 ## Included content
-
 <!--start collection content-->
-### Inventory plugins
-Name | Description
---- | ---
-[amazon.aws.aws_ec2](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.aws_ec2_inventory.rst)|EC2 inventory source
-[amazon.aws.aws_rds](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.aws_rds_inventory.rst)|rds instance source
-
-### Lookup plugins
-Name | Description
---- | ---
-[amazon.aws.aws_account_attribute](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.aws_account_attribute_lookup.rst)|Look up AWS account attributes.
-[amazon.aws.aws_secret](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.aws_secret_lookup.rst)|Look up secrets stored in AWS Secrets Manager.
-[amazon.aws.aws_service_ip_ranges](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.aws_service_ip_ranges_lookup.rst)|Look up the IP ranges for services provided in AWS such as EC2 and S3.
-[amazon.aws.aws_ssm](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.aws_ssm_lookup.rst)|Get the value for a SSM parameter or all parameters under a path.
-
-### Modules
-Name | Description
---- | ---
-[amazon.aws.aws_az_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.aws_az_info_module.rst)|Gather information about availability zones in AWS
-[amazon.aws.aws_caller_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.aws_caller_info_module.rst)|Get information about the user and account being used to make AWS calls
-[amazon.aws.cloudformation](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.cloudformation_module.rst)|Create or delete an AWS CloudFormation stack
-[amazon.aws.cloudformation_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.cloudformation_info_module.rst)|Obtain information about an AWS CloudFormation stack
-[amazon.aws.ec2_ami](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_ami_module.rst)|Create or destroy an image (AMI) in ec2
-[amazon.aws.ec2_ami_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_ami_info_module.rst)|Gather information about ec2 AMIs
-[amazon.aws.ec2_eni](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_eni_module.rst)|Create and optionally attach an Elastic Network Interface (ENI) to an instance
-[amazon.aws.ec2_eni_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_eni_info_module.rst)|Gather information about ec2 ENI interfaces in AWS
-[amazon.aws.ec2_group](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_group_module.rst)|Maintain an ec2 VPC security group
-[amazon.aws.ec2_group_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_group_info_module.rst)|Gather information about ec2 security groups in AWS
-[amazon.aws.ec2_instance](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_instance_module.rst)|Create & manage EC2 instances
-[amazon.aws.ec2_instance_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_instance_info_module.rst)|Gather information about ec2 instances in AWS
-[amazon.aws.ec2_key](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_key_module.rst)|Create or delete an ec2 key pair
-[amazon.aws.ec2_metadata_facts](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_metadata_facts_module.rst)|Gathers facts (instance metadata) about remote hosts within EC2
-[amazon.aws.ec2_snapshot](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_snapshot_module.rst)|Creates a snapshot from an existing volume
-[amazon.aws.ec2_snapshot_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_snapshot_info_module.rst)|Gathers information about EC2 volume snapshots in AWS
-[amazon.aws.ec2_spot_instance](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_spot_instance_module.rst)|Request, stop, reboot or cancel spot instance
-[amazon.aws.ec2_spot_instance_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_spot_instance_info_module.rst)|Gather information about ec2 spot instance requests
-[amazon.aws.ec2_tag](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_tag_module.rst)|Create and remove tags on ec2 resources
-[amazon.aws.ec2_tag_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_tag_info_module.rst)|List tags on ec2 resources
-[amazon.aws.ec2_vol](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vol_module.rst)|Create and attach a volume, return volume id and device map
-[amazon.aws.ec2_vol_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vol_info_module.rst)|Gather information about ec2 volumes in AWS
-[amazon.aws.ec2_vpc_dhcp_option](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_dhcp_option_module.rst)|Manages DHCP Options, and can ensure the DHCP options for the given VPC match what's requested
-[amazon.aws.ec2_vpc_dhcp_option_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_dhcp_option_info_module.rst)|Gather information about dhcp options sets in AWS
-[amazon.aws.ec2_vpc_endpoint](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_endpoint_module.rst)|Create and delete AWS VPC Endpoints.
-[amazon.aws.ec2_vpc_endpoint_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_endpoint_info_module.rst)|Retrieves AWS VPC endpoints details using AWS methods
-[amazon.aws.ec2_vpc_endpoint_service_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_endpoint_service_info_module.rst)|Retrieves AWS VPC endpoint service details
-[amazon.aws.ec2_vpc_igw](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_igw_module.rst)|Manage an AWS VPC Internet gateway
-[amazon.aws.ec2_vpc_igw_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_igw_info_module.rst)|Gather information about internet gateways in AWS
-[amazon.aws.ec2_vpc_nat_gateway](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_nat_gateway_module.rst)|Manage AWS VPC NAT Gateways
-[amazon.aws.ec2_vpc_nat_gateway_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_nat_gateway_info_module.rst)|Retrieves AWS VPC Managed Nat Gateway details using AWS methods
-[amazon.aws.ec2_vpc_net](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_net_module.rst)|Configure AWS virtual private clouds
-[amazon.aws.ec2_vpc_net_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_net_info_module.rst)|Gather information about ec2 VPCs in AWS
-[amazon.aws.ec2_vpc_route_table](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_route_table_module.rst)|Manage route tables for AWS virtual private clouds
-[amazon.aws.ec2_vpc_route_table_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_route_table_info_module.rst)|Gather information about ec2 VPC route tables in AWS
-[amazon.aws.ec2_vpc_subnet](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_subnet_module.rst)|Manage subnets in AWS virtual private clouds
-[amazon.aws.ec2_vpc_subnet_info](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.ec2_vpc_subnet_info_module.rst)|Gather information about ec2 VPC subnets in AWS
-[amazon.aws.elb_classic_lb](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.elb_classic_lb_module.rst)|Creates, updates or destroys an Amazon ELB
-[amazon.aws.s3_bucket](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.s3_bucket_module.rst)|Manage S3 buckets in AWS, DigitalOcean, Ceph, Walrus, FakeS3 and StorageGRID
-[amazon.aws.s3_object](https://github.com/ansible-collections/amazon.aws/blob/stable-4/docs/amazon.aws.s3_object_module.rst)|Manage objects in S3
+See the complete list of collection content in the [Plugin Index](https://ansible-collections.github.io/amazon.aws/branch/main/collections/amazon/aws/index.html#plugin-index).
 
 <!--end collection content-->
 
@@ -147,8 +90,6 @@ You can either call modules by their Fully Qualified Collection Namespace (FQCN)
     register: instance
 ```
 
-**NOTE**: For Ansible 2.9, you may not see deprecation warnings when you run your playbooks with this collection. Use this documentation to track when a module is deprecated.
-
 
 ### See Also: