Merge pull request #82 from joshbeard/doc-updates

docs: add descriptions, example, linting, etc

README.md

@@ -53,32 +53,32 @@ Create a category:
 
 ```terraform
 resource "readme_category" "example" {
-    title = "My example category"
-    type  = "guide"
+  title = "My example category"
+  type  = "guide"
 }
 ```
 
 Create a doc:
 
 ```terraform
 resource "readme_doc" "example" {
-    # title can be specified as an attribute or in the body front matter.
-    title = "My Example Doc"
+  # title can be specified as an attribute or in the body front matter.
+  title = "My Example Doc"
 
-    # category_slug can be specified as an attribute or in the body front matter.
-    category_slug = readme_category.example.slug
+  # category_slug can be specified as an attribute or in the body front matter.
+  category_slug = readme_category.example.slug
 
-    # hidden can be specified as an attribute or in the body front matter.
-    hidden = false
+  # hidden can be specified as an attribute or in the body front matter.
+  hidden = false
 
-    # order can be specified as an attribute or in the body front matter.
-    order = 99
+  # order can be specified as an attribute or in the body front matter.
+  order = 99
 
-    # type can be specified as an attribute or in the body front matter.
-    type = "basic"
+  # type can be specified as an attribute or in the body front matter.
+  type = "basic"
 
-    # body can be read from a file using Terraform's `file()` function.
-    body = file("mydoc.md")
+  # body can be read from a file using Terraform's `file()` function.
+  body = file("mydoc.md")
 }
 ```
 

docs/data-sources/api_registry.md

@@ -27,11 +27,11 @@ data "readme_api_registry" "example" {
 
 # Output the API specification from the registry.
 output "example_api_registry" {
-    value = data.readme_api_registry.example.definition
+  value = data.readme_api_registry.example.definition
 }
 
 output "example_registry_uuid" {
-    value = data.readme_api_registry.example.uuid
+  value = data.readme_api_registry.example.uuid
 }
 ```
 

docs/data-sources/categories.md

@@ -20,7 +20,7 @@ See <https://docs.readme.com/main/reference/getcategories> for more information
 data "readme_categories" "example" {}
 
 output "categories" {
-    value = data.readme_categories.example
+  value = data.readme_categories.example
 }
 ```
 

docs/data-sources/category.md

@@ -18,11 +18,11 @@ See <https://docs.readme.com/main/reference/getcategory> for more information ab
 ```terraform
 # The "readme_category" data source retrieves a single category's metadata.
 data "readme_category" "example" {
-    slug = "example"
+  slug = "example"
 }
 
 output "category" {
-    value = data.readme_category.example
+  value = data.readme_category.example
 }
 ```
 

docs/data-sources/category_docs.md

@@ -18,11 +18,11 @@ See <https://docs.readme.com/main/reference/getcategorydocs> for more informatio
 ```terraform
 # The "readme_category_docs" data source retrieves a list of docs for a category.
 data "readme_category_docs" "example" {
-    slug = "example"
+  slug = "example"
 }
 
 output "category_docs" {
-    value = data.readme_category_docs.example
+  value = data.readme_category_docs.example
 }
 ```
 

docs/data-sources/custom_page.md

@@ -18,11 +18,11 @@ See <https://docs.readme.com/reference/getcustompages> for more information abou
 ```terraform
 # Retrieve a single custom page by its slug.
 data "readme_custom_page" "example" {
-    slug = "my-example-custom-page"
+  slug = "my-example-custom-page"
 }
 
 output "example" {
-    value = data.readme_custom_page.example
+  value = data.readme_custom_page.example
 }
 ```
 

docs/data-sources/custom_pages.md

@@ -20,7 +20,7 @@ See <https://docs.readme.com/reference/getcustompages> for more information abou
 data "readme_custom_pages" "example" {}
 
 output "example" {
-    value = data.readme_custom_pages.example
+  value = data.readme_custom_pages.example
 }
 ```
 

docs/data-sources/doc.md

@@ -18,11 +18,11 @@ See <https://docs.readme.com/main/reference/getdoc> for more information about t
 ```terraform
 # Retrieve a doc from ReadMe.
 data "readme_doc" "example" {
-    slug = "my-example-doc"
+  slug = "my-example-doc"
 }
 
 output "example_doc" {
-    value = data.readme_doc.example
+  value = data.readme_doc.example
 }
 ```
 

docs/data-sources/doc_search.md

@@ -13,7 +13,18 @@ Retrieve docs matching a search query on ReadMe.com
 
 See <https://docs.readme.com/main/reference/getdoc> for more information about this API endpoint.
 
-
+## Example Usage
+
+```terraform
+# Search for docs on ReadMe.
+data "readme_doc_search" "example" {
+  query = "*"
+}
+
+output "example_doc_search" {
+  value = data.readme_doc_search.example
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/data-sources/project.md

@@ -26,17 +26,17 @@ data "readme_project" "example" {}
 # Output all project metadata.
 # This output is redacted because the jwtSecret is marked sensitive.
 output "example_project" {
-    value     = data.readme_project.example
-    sensitive = true
+  value     = data.readme_project.example
+  sensitive = true
 }
 
 # Output a single attribute
 output "example_project_name" {
-    value = data.readme_project.example.name
+  value = data.readme_project.example.name
 }
 
 output "example_project_base_url" {
-    value = data.readme_project.example.base_url
+  value = data.readme_project.example.base_url
 }
 ```
 

docs/data-sources/version.md

@@ -18,15 +18,15 @@ See <https://docs.readme.com/main/reference/getversion> for more information abo
 ```terraform
 # The "readme_version" data source retrieves metadata about a version on ReadMe.com.
 data "readme_version" "example" {
-    # Use the 'version' or 'version_clean' attributes to look up a version.
-    # For best results, use 'version_clean'.
-    # version = "1.0.1"
-    version_clean = "1.0.1"
+  # Use the 'version' or 'version_clean' attributes to look up a version.
+  # For best results, use 'version_clean'.
+  # version = "1.0.1"
+  version_clean = "1.0.1"
 }
 
 # Output all version metadata.
 output "example_version" {
-    value = data.readme_version.example
+  value = data.readme_version.example
 }
 ```
 

docs/data-sources/versions.md

@@ -21,12 +21,12 @@ data "readme_versions" "example" {}
 
 # Return the full list.
 output "example_versions" {
-    value = data.readme_versions.example.versions
+  value = data.readme_versions.example.versions
 }
 
 # Retrieve a specific attribute from version in the list.
 output "example_version_detail" {
-    value = tolist(data.readme_versions.example.versions)[0].version
+  value = tolist(data.readme_versions.example.versions)[0].version
 }
 ```
 

docs/resources/api_specification.md

@@ -8,7 +8,7 @@ description: |-
   External Changes
   External changes made to an API specification managed by Terraform will not be detected due to the way the API registry works. When a specification definition is updated, the registry UUID changes and is only available from the response when the definition is published to the registry. When Terraform runs after an external update, there's no way of programatically retrieving the current state without the current UUID. Forcing a Terraform update (e.g. tainting or a manual change) will get things synchronized again.
   Importing Existing Specifications
-  Importing API specifications is also limited due to the behavior of the API registry and associating a specification with its definition. When importing, Terraform will replace the remote definition on its next run, regardless if it differs from the local definition. This will associate a registry UUID with the specification.
+  Importing API specifications is limited due to the behavior of the API registry and associating a specification with its definition. When importing, Terraform will replace the remote definition on its next run, regardless if it differs from the local definition. This will associate a registry UUID with the specification.
   See https://docs.readme.com/main/reference/uploadapispecification for more information about this API endpoint.
 ---
 
@@ -24,7 +24,7 @@ External changes made to an API specification managed by Terraform will not be d
 
 ## Importing Existing Specifications
 
-Importing API specifications is also limited due to the behavior of the API registry and associating a specification with its definition. When importing, Terraform will replace the remote definition on its next run, regardless if it differs from the local definition. This will associate a registry UUID with the specification.
+Importing API specifications is limited due to the behavior of the API registry and associating a specification with its definition. When importing, Terraform will replace the remote definition on its next run, regardless if it differs from the local definition. This will associate a registry UUID with the specification.
 
 See <https://docs.readme.com/main/reference/uploadapispecification> for more information about this API endpoint.
 

docs/resources/category.md

@@ -18,8 +18,8 @@ See <https://docs.readme.com/main/reference/getcategory> for more information ab
 ```terraform
 # The "readme_category" resource manages the lifecycle of a category in ReadMe.
 resource "readme_category" "example" {
-    title = "My example category"
-    type  = "guide"
+  title = "My example category"
+  type  = "guide"
 }
 ```
 

docs/resources/custom_page.md

@@ -4,18 +4,21 @@ page_title: "readme_custom_page Resource - readme"
 subcategory: ""
 description: |-
   Manage custom pages on ReadMe.com
-  See https://docs.readme.com/main/reference/createcustompage for more information about this API endpoint.
+  Custom pages on ReadMe support setting some attributes using front matter. Resource attributes take precedence over front matter attributes in the provider.
   Refer to https://docs.readme.com/main/docs/rdme for more information about using front matter in ReadMe docs and custom pages.
+  See https://docs.readme.com/main/reference/createcustompage for more information about this API endpoint.
 ---
 
 # readme_custom_page (Resource)
 
 Manage custom pages on ReadMe.com
 
-See <https://docs.readme.com/main/reference/createcustompage> for more information about this API endpoint.
+Custom pages on ReadMe support setting some attributes using front matter. Resource attributes take precedence over front matter attributes in the provider.
 
 Refer to <https://docs.readme.com/main/docs/rdme> for more information about using front matter in ReadMe docs and custom pages.
 
+See <https://docs.readme.com/main/reference/createcustompage> for more information about this API endpoint.
+
 ## Example Usage
 
 ```terraform
@@ -44,11 +47,11 @@ resource "readme_custom_page" "example_html" {
 
 ### Optional
 
-- `body` (String) The body of the custom page.
-- `hidden` (Boolean) Whether the custom page is hidden.
+- `body` (String) The body of the custom page. Optionally use front matter to set certain attributes. Alternatively, use the `html_mode` and `html` attributes to set the body in HTML format.
+- `hidden` (Boolean) Whether the custom page is hidden. This can alternatively be set using the `hidden` front matter key.
 - `html` (String) The body source formatted in HTML. Only displayed if `htmlmode` is set to `true`. Leading and trailing whitespace and certain HTML tags are removed when uploaded to ReadMe. The `html_clean` attribute will contain the normalized HTML.
 - `html_mode` (Boolean) Set to `true` if `html` should be displayed, otherwise `body` will be displayed.
-- `title` (String) The title of the custom page. This can also be set using the `title` front matter.
+- `title` (String) The title of the custom page. This can alternatively be set using the `title` front matter key.
 
 ### Read-Only
 
@@ -81,3 +84,12 @@ Read-Only:
 - `description` (String)
 - `image` (List of String)
 - `title` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Import a custom page using its slug.
+terraform import readme_custom_page.example example-slug
+```

docs/resources/doc.md

@@ -4,20 +4,20 @@ page_title: "readme_doc Resource - readme"
 subcategory: ""
 description: |-
   Manage docs on ReadMe.com
+  Docs on ReadMe support setting some attributes using front matter. Resource attributes take precedence over front matter attributes in the provider.
+  Refer to https://docs.readme.com/main/docs/rdme for more information about using front matter in ReadMe docs and custom pages.
   See https://docs.readme.com/main/reference/getdoc for more information about this API endpoint.
-  All of the optional attributes except body may alternatively be set in the body's front matter. Attributes take precedence over values set in front matter.
-  Refer to https://docs.readme.com/main/docs/rdme for more information about using front matter in ReadMe docs.
 ---
 
 # readme_doc (Resource)
 
 Manage docs on ReadMe.com
 
-See <https://docs.readme.com/main/reference/getdoc> for more information about this API endpoint.
+Docs on ReadMe support setting some attributes using front matter. Resource attributes take precedence over front matter attributes in the provider.
 
-All of the optional attributes except `body` may alternatively be set in the body's front matter. Attributes take precedence over values set in front matter.
+Refer to <https://docs.readme.com/main/docs/rdme> for more information about using front matter in ReadMe docs and custom pages.
 
-Refer to <https://docs.readme.com/main/docs/rdme> for more information about using front matter in ReadMe docs.
+See <https://docs.readme.com/main/reference/getdoc> for more information about this API endpoint.
 
 ## Example Usage
 
@@ -64,13 +64,9 @@ resource "readme_doc" "example" {
 
 ### Optional
 
-- `body` (String) The body content of the doc, formatted in ReadMe or GitHub flavored Markdown. Accepts long page content, for example, greater than 100k characters.
-- `category` (String) **Required**. The category ID of the doc. Note that changing the category will result in a replacement of the doc resource. This attribute may optionally be set in the body front matter or with the `category_slug` attribute.
-
-Docs that specify a `parent_doc` or `parent_doc_slug` will use their parent's category.
-- `category_slug` (String) **Required**. The category ID of the doc. Note that changing the category will result in a replacement of the doc resource. This attribute may optionally be set in the body front matter with the `categorySlug` key or with the `category` attribute.
-
-Docs that specify a `parent_doc` or `parent_doc_slug` will use their parent's category.
+- `body` (String) The body content of the doc, formatted in ReadMe or GitHub flavored Markdown. Accepts long page content, for example, greater than 100k characters. Optionally use front matter to set certain attributes.
+- `category` (String) **Required**. The category ID of the doc. Note that changing the category will result in a replacement of the doc resource. Alternatively, set the `category` key the body front matter. Docs that specify a `parent_doc` or `parent_doc_slug` will use their parent's category.
+- `category_slug` (String) **Required**. The category slug of the doc. Note that changing the category will result in a replacement of the doc resource. Alternatively, set the `categorySlug` key the body front matter. Docs that specify a `parent_doc` or `parent_doc_slug` will use their parent's category.
 - `error` (Attributes) Error code configuration for a doc. This attribute may be set in the body front matter. (see [below for nested schema](#nestedatt--error))
 - `hidden` (Boolean) Toggles if a doc is hidden or not. This attribute may be set in the body front matter.
 - `order` (Number) The position of the doc in the project sidebar. This attribute may be set in the body front matter.
@@ -88,17 +84,17 @@ Docs that specify a `parent_doc` or `parent_doc_slug` will use their parent's ca
 - `body_clean` (String) The body content of the doc after transformations such as trimming leading and trailingspaces.
 - `body_html` (String) The body content in HTML.
 - `created_at` (String) Timestamp of when the version was created.
-- `deprecated` (Boolean) Toggles if a doc is deprecated or not.
+- `deprecated` (Boolean) Identifies if a doc is deprecated or not.
 - `excerpt` (String) A short summary of the content.
 - `icon` (String)
 - `id` (String) The ID of the doc.
-- `is_api` (Boolean)
-- `is_reference` (Boolean)
-- `link_external` (Boolean)
-- `link_url` (String)
-- `metadata` (Attributes) (see [below for nested schema](#nestedatt--metadata))
+- `is_api` (Boolean) Identifies if a doc is an API doc or not.
+- `is_reference` (Boolean) Identifies if a doc is a reference doc or not.
+- `link_external` (Boolean) Identifies a doc's link as external or not.
+- `link_url` (String) The URL of the doc.
+- `metadata` (Attributes) Metadata about the doc. (see [below for nested schema](#nestedatt--metadata))
 - `next` (Attributes) Information about the 'next' pages in a series. (see [below for nested schema](#nestedatt--next))
-- `previous_slug` (String)
+- `previous_slug` (String) If the doc's slug has changed, this attribute contains the previous slug.
 - `project` (String) The ID of the project the doc is in.
 - `revision` (Number) A number that is incremented upon doc updates.
 - `slug` (String) The slug of the doc.
@@ -197,9 +193,9 @@ Read-Only:
 
 Read-Only:
 
-- `description` (String)
-- `image` (List of String)
-- `title` (String)
+- `description` (String) The description of the doc.
+- `image` (List of String) An image associated with the doc.
+- `title` (String) The title of the doc.
 
 
 <a id="nestedatt--next"></a>

docs/resources/image.md

@@ -21,11 +21,11 @@ Images are not truly stateful - the provider tracks the local source image for c
 ```terraform
 # Upload an image to ReadMe.
 resource "readme_image" "example" {
-    source = "example.png"
+  source = "example.png"
 }
 
 output "image_info" {
-    value = readme_image.example
+  value = readme_image.example
 }
 ```