Merge pull request ekristen#391 from ekristen/resource-docs

feat: resource documentation

docs/development.md

@@ -12,6 +12,8 @@ goreleaser build --clean --snapshot --single-target
 
 This is built using Material for MkDocs and can be run very easily locally providing you have docker available.
 
+[Read more about it here.](documentation.md)
+
 ### Running Locally
 
 ```console

docs/documentation.md

@@ -0,0 +1,39 @@
+## Overview
+
+This documentation is generated using Material for MkDocs and can be run very easily locally providing you have docker
+available.
+
+All documentation resides within the `docs` directory and is written in markdown. The `mkdocs.yml` file is used to
+configure the site and the `docs` directory is used to store the markdown files.
+
+### Running Locally
+
+```console
+make docs-serve
+```
+
+## Resource Documentation
+
+With `version 3` of aws-nuke we have introduced a new feature to allow generating documentation for resources. This
+feature is still in its early stages, and we are working on adding more resources to it. If you would like to help us
+with this, please feel free to contribute to the project.
+
+Please see [Converting a resource for self documenting](resources.md#converting-a-resource-for-self-documenting) for
+more information on how to properly convert an existing resource to be self documenting.
+
+!!! note
+    Not all resources can have documentation generated with this feature. It must be implemented for each resource
+    individually.
+
+### How It Works
+
+The underlying library that drives the bulk of this tool is [libnuke](https://github.com/ekristen/libnuke). This library
+has tooling to help generate documentation for a resource. Primary the library focuses on inspecting the resource struct
+and generating documentation based on the fields of the struct for properties.
+
+There's an additional sub command called `generate-resource-docs` that is hidden from standard usage. This command is
+used to generate documentation for a resource and write it to disk. This command leverages the struct inspection to get
+details about the properties and intertwine them with the markdown template to generate the documentation.
+
+However, for this to work the resource needs to be updated to export all it's fields. This is done by capitalizing the
+first letter of the field name. The field name should match what the existing property name is if it is defined.

docs/resources.md

@@ -168,3 +168,139 @@ redirect to a file like so:
 go run tools/create-resource/main.go <service> <resource-type> > resources/<resource-type>.go
 ```
 
+## Converting a resource for self documenting
+
+To convert a resource for self documenting, you need to do the following:
+
+- Write a test for the resource to verify its current properties
+- Add the `Resource` field to the registration struct
+- Capitalize the first letter of the field names
+- Match the field names to the property names that are defined in `Properties()` method
+- Switch to `NewPropertiesFromStruct` method in `Properties()` method
+- Run the tests to verify the properties are still correct
+- Run the `generate-resource-docs` command to generate the documentation
+- Commit your changes and open a pull request
+
+### Example
+
+**Before**
+
+```go
+package resources
+
+import (
+	"context"
+
+	"fmt"
+
+	"github.com/aws/aws-sdk-go/service/sns"
+
+	"github.com/ekristen/libnuke/pkg/registry"
+	"github.com/ekristen/libnuke/pkg/resource"
+	"github.com/ekristen/libnuke/pkg/types"
+
+	"github.com/ekristen/aws-nuke/v3/pkg/nuke"
+)
+
+const SNSTopicResource = "SNSTopic"
+
+func init() {
+	registry.Register(&registry.Registration{
+		Name:   SNSTopicResource,
+		Scope:  nuke.Account,
+		Lister: &SNSTopicLister{},
+	})
+}
+
+type SNSTopic struct {
+	svc  *sns.SNS
+	id   *string
+	tags []*sns.Tag
+}
+
+func (r *SNSTopic) Remove(_ context.Context) error {
+	_, err := r.svc.DeleteTopic(&sns.DeleteTopicInput{
+		TopicArn: r.id,
+	})
+	return err
+}
+
+func (r *SNSTopic) Properties() types.Properties {
+	properties := types.NewProperties()
+
+	for _, tag := range r.tags {
+		properties.SetTag(tag.Key, tag.Value)
+	}
+	properties.Set("TopicARN", r.id)
+
+	return properties
+}
+
+func (r *SNSTopic) String() string {
+	return fmt.Sprintf("TopicARN: %s", *r.id)
+}
+
+type SNSTopicLister struct{}
+
+func (l *SNSTopicLister) List(_ context.Context, _ interface{}) ([]resource.Resource, error) {
+	return nil, nil
+}
+```
+
+**After**
+
+```go
+package resources
+
+import (
+	"context"
+
+	"fmt"
+
+	"github.com/aws/aws-sdk-go/service/sns"
+
+	"github.com/ekristen/libnuke/pkg/registry"
+	"github.com/ekristen/libnuke/pkg/resource"
+	"github.com/ekristen/libnuke/pkg/types"
+
+	"github.com/ekristen/aws-nuke/v3/pkg/nuke"
+)
+
+const SNSTopicResource = "SNSTopic"
+
+func init() {
+	registry.Register(&registry.Registration{
+		Name:     SNSTopicResource,
+		Scope:    nuke.Account,
+		Resource: &SNSTopic{},
+		Lister:   &SNSTopicLister{},
+	})
+}
+
+type SNSTopic struct {
+	svc      *sns.SNS
+	TopicARN *string
+	Tags     []*sns.Tag
+}
+
+func (r *SNSTopic) Remove(_ context.Context) error {
+	_, err := r.svc.DeleteTopic(&sns.DeleteTopicInput{
+		TopicArn: r.TopicARN,
+	})
+	return err
+}
+
+func (r *SNSTopic) Properties() types.Properties {
+	return types.NewPropertiesFromStruct(r)
+}
+
+func (r *SNSTopic) String() string {
+	return fmt.Sprintf("TopicARN: %s", *r.TopicARN)
+}
+
+type SNSTopicLister struct{}
+
+func (l *SNSTopicLister) List(_ context.Context, _ interface{}) ([]resource.Resource, error) {
+	return nil, nil
+}
+```

docs/resources/access-analyzer-archive-rule.md

@@ -0,0 +1,38 @@
+---
+generated: true
+---
+
+# AccessAnalyzerArchiveRule
+
+
+## Resource
+
+```text
+AccessAnalyzerArchiveRule
+```
+
+## Properties
+
+
+- `AnalyzerName`: The name of the analyzer the rule is associated with
+- `RuleName`: The name of the archive rule
+
+!!! note - Using Properties
+    Properties are what [Filters](../config-filtering.md) are written against in your configuration. You use the property
+    names to write filters for what you want to **keep** and omit from the nuke process.
+
+### String Property
+
+The string representation of a resource is generally the value of the Name, ID or ARN field of the resource. Not all
+resources support properties. To write a filter against the string representation, simply omit the `property` field in
+the filter.
+
+The string value is always what is used in the output of the log format when a resource is identified.
+
+## Deprecated Aliases
+
+!!! warning
+    This resource has deprecated aliases associated with it. Deprecated Aliases will be removed in the next major
+    release of aws-nuke. Please update your configuration to use the new resource name.
+
+- `ArchiveRule`

docs/resources/access-analyzer.md

@@ -0,0 +1,43 @@
+---
+generated: true
+---
+
+# AccessAnalyzer
+
+
+## Resource
+
+```text
+AccessAnalyzer
+```
+
+### Alternative Resource
+
+!!! note - Cloud Control API - Alternative Resource
+    This resource can also be controlled and used via Cloud Control API. Please refer to the documentation for
+    [Cloud Control Resources](../config-cloud-control.md) for more information.
+
+```text
+AWS::AccessAnalyzer::Analyzer
+```
+## Properties
+
+
+- `ARN`: The ARN of the analyzer
+- `Name`: The name of the analyzer
+- `Status`: The status of the analyzer
+- `tag:<key>:`: This resource has tags with property `Tags`. These are key/value pairs that are
+	added as their own property with the prefix of `tag:` (e.g. [tag:example: "value"]) 
+
+!!! note - Using Properties
+    Properties are what [Filters](../config-filtering.md) are written against in your configuration. You use the property
+    names to write filters for what you want to **keep** and omit from the nuke process.
+
+### String Property
+
+The string representation of a resource is generally the value of the Name, ID or ARN field of the resource. Not all
+resources support properties. To write a filter against the string representation, simply omit the `property` field in
+the filter.
+
+The string value is always what is used in the output of the log format when a resource is identified.
+

docs/resources/acm-certificate.md

@@ -0,0 +1,35 @@
+---
+generated: true
+---
+
+# ACMCertificate
+
+
+## Resource
+
+```text
+ACMCertificate
+```
+
+## Properties
+
+
+- `ARN`: The ARN of the certificate
+- `CreatedAt`: The creation time of the certificate
+- `DomainName`: The domain name of the certificate
+- `Status`: The status of the certificate
+- `tag:<key>:`: This resource has tags with property `Tags`. These are key/value pairs that are
+	added as their own property with the prefix of `tag:` (e.g. [tag:example: "value"]) 
+
+!!! note - Using Properties
+    Properties are what [Filters](../config-filtering.md) are written against in your configuration. You use the property
+    names to write filters for what you want to **keep** and omit from the nuke process.
+
+### String Property
+
+The string representation of a resource is generally the value of the Name, ID or ARN field of the resource. Not all
+resources support properties. To write a filter against the string representation, simply omit the `property` field in
+the filter.
+
+The string value is always what is used in the output of the log format when a resource is identified.
+

docs/resources/acmpca-certificate-authority-state.md

@@ -0,0 +1,33 @@
+---
+generated: true
+---
+
+# ACMPCACertificateAuthorityState
+
+
+## Resource
+
+```text
+ACMPCACertificateAuthorityState
+```
+
+## Properties
+
+
+- `ARN`: The Amazon Resource Name (ARN) that was assigned to the CA when it was created.
+- `Status`: The status of the CA, indicating whether it is active, creating, pending_certificate, disabled, or deleted.
+- `tag:<key>:`: This resource has tags with property `Tags`. These are key/value pairs that are
+	added as their own property with the prefix of `tag:` (e.g. [tag:example: "value"]) 
+
+!!! note - Using Properties
+    Properties are what [Filters](../config-filtering.md) are written against in your configuration. You use the property
+    names to write filters for what you want to **keep** and omit from the nuke process.
+
+### String Property
+
+The string representation of a resource is generally the value of the Name, ID or ARN field of the resource. Not all
+resources support properties. To write a filter against the string representation, simply omit the `property` field in
+the filter.
+
+The string value is always what is used in the output of the log format when a resource is identified.
+

docs/resources/acmpca-certificate-authority.md

@@ -0,0 +1,42 @@
+---
+generated: true
+---
+
+# ACMPCACertificateAuthority
+
+
+## Resource
+
+```text
+ACMPCACertificateAuthority
+```
+
+### Alternative Resource
+
+!!! note - Cloud Control API - Alternative Resource
+    This resource can also be controlled and used via Cloud Control API. Please refer to the documentation for
+    [Cloud Control Resources](../config-cloud-control.md) for more information.
+
+```text
+AWS::ACMPCA::CertificateAuthority
+```
+## Properties
+
+
+- `ARN`: The Amazon Resource Name (ARN) of the private CA.
+- `Status`: Status of the private CA.
+- `tag:<key>:`: This resource has tags with property `Tags`. These are key/value pairs that are
+	added as their own property with the prefix of `tag:` (e.g. [tag:example: "value"]) 
+
+!!! note - Using Properties
+    Properties are what [Filters](../config-filtering.md) are written against in your configuration. You use the property
+    names to write filters for what you want to **keep** and omit from the nuke process.
+
+### String Property
+
+The string representation of a resource is generally the value of the Name, ID or ARN field of the resource. Not all
+resources support properties. To write a filter against the string representation, simply omit the `property` field in
+the filter.
+
+The string value is always what is used in the output of the log format when a resource is identified.
+