Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Replace old doc generation process with new tfplugindocs tool #356

Merged
merged 43 commits into from
Jan 29, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
43 commits
Select commit Hold shift + click to select a range
5bba9f9
rename directories
Integralist Jan 25, 2021
75b4ea2
move index page (it doesn't appear to be dynamially generated)
Integralist Jan 25, 2021
70f9c66
remove old ruby file no longer needed
Integralist Jan 25, 2021
7380124
rename obsolete file as code implementation requires it to continue t…
Integralist Jan 25, 2021
1766d34
todo
Integralist Jan 26, 2021
2671c9f
update README
Integralist Jan 26, 2021
d3cb7dc
rename and regenerate all pages
Integralist Jan 26, 2021
7776fc2
remove no-op file and print statement
Integralist Jan 26, 2021
00f2482
updated Markdown generated from tfplugindocs
Integralist Jan 26, 2021
b2efacb
tweak README to include online preview tool
Integralist Jan 26, 2021
cb89c5b
clarifying notes
Integralist Jan 26, 2021
9b921d6
rename docs_src to templates and regenerate content
Integralist Jan 26, 2021
0433b0a
update README
Integralist Jan 26, 2021
7ea6eb7
update Makefile
Integralist Jan 26, 2021
1e8578b
update README with new Makefile targets
Integralist Jan 26, 2021
e10374e
use SchemaMarkdown to render existing template content
Integralist Jan 26, 2021
2222721
remove obsolete yaml frontmatter
Integralist Jan 26, 2021
9862c36
steps to get this thing working
Integralist Jan 26, 2021
4d430d3
remove generated docs
Integralist Jan 26, 2021
8d8c755
run tfplugindocs generate
Integralist Jan 26, 2021
4b21af5
final step
Integralist Jan 26, 2021
bce4f8c
update README and Makefile
Integralist Jan 26, 2021
fbeb568
remove print of temp directory
Integralist Jan 26, 2021
4b08c33
docs
Integralist Jan 26, 2021
2fa9408
rename script to generate docs
Integralist Jan 27, 2021
a9139cc
remove CI website check
Integralist Jan 27, 2021
5d56048
sometimes the github markdown renderer gets confused and doesn't rend…
Integralist Jan 27, 2021
ed6d11d
update renamed makefile target
Integralist Jan 27, 2021
7fc608d
make README code use consistent
Integralist Jan 27, 2021
0e93c3a
add link to terraform documentation
Integralist Jan 27, 2021
f370999
fix typo in Makefile PHONY definition
Integralist Jan 27, 2021
4390d1f
add missing index page
Integralist Jan 27, 2021
8c7faa2
fix bug in docs generation where index.md was omitted
Integralist Jan 27, 2021
26dac20
Fix bug where index.md was missing
Integralist Jan 27, 2021
d96f2a9
remove attr ref from ip ranges
Integralist Jan 27, 2021
4f15842
remove arg ref from acl entries
Integralist Jan 27, 2021
65b6051
add missing descriptions related to service resources
Integralist Jan 27, 2021
b454bb4
multiple documentation updates/fixes
Integralist Jan 27, 2021
43b1655
replace docs link with dev link
Integralist Jan 28, 2021
fad370a
replace function with Getwd()
Integralist Jan 28, 2021
edc75bf
revert frontmatter deletions
Integralist Jan 28, 2021
d120a09
regenerate docs with frontmatter put back
Integralist Jan 28, 2021
0ac5ebe
delete no longer used templates as generated by schema data
Integralist Jan 28, 2021
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 0 additions & 29 deletions .github/workflows/pr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -43,32 +43,3 @@ jobs:
${{ runner.os }}-go-mod-
- name: Test
run: make test
website:
Integralist marked this conversation as resolved.
Show resolved Hide resolved
runs-on: ubuntu-latest
steps:
- name: Install Go
uses: actions/setup-go@v2
with:
go-version: 1.14.x
- name: Set Go variables for backwards compatibility
run: |
echo "GOPATH=$GITHUB_WORKSPACE/go" >> $GITHUB_ENV
- name: Checkout code
uses: actions/checkout@v2
with:
path: go/src/github.com/${{ github.repository }}
- name: Checkout code
uses: actions/checkout@v2
with:
repository: 'hashicorp/terraform-website'
path: go/src/github.com/hashicorp/terraform-website
- name: Run website-test
run: |
cd $GOPATH/src/github.com/${{ github.repository }}
ln -sf ../../../../ext/providers/fastly/website/docs $GOPATH/src/github.com/hashicorp/terraform-website/content/source/docs/providers/fastly
ln -sf ../../../../ext/providers/fastly/website/fastly.erb $GOPATH/src/github.com/hashicorp/terraform-website/content/source/layouts/fastly.erb
make website-test
- name: Check diff
run: |
cd $GOPATH/src/github.com/${{ github.repository }}
git diff-files --ignore-all-space --name-only --exit-code
21 changes: 5 additions & 16 deletions GNUmakefile
Original file line number Diff line number Diff line change
Expand Up @@ -52,21 +52,10 @@ test-compile:
fi
go test -c $(TEST) $(TESTARGS)

website:
ifeq (,$(wildcard $(GOPATH)/src/$(WEBSITE_REPO)))
echo "$(WEBSITE_REPO) not found in your GOPATH (necessary for layouts and assets), get-ting..."
git clone https://$(WEBSITE_REPO) $(GOPATH)/src/$(WEBSITE_REPO)
endif
go run "scripts/website/parse-templates.go"
@$(MAKE) -C $(GOPATH)/src/$(WEBSITE_REPO) website-provider PROVIDER_PATH=$(shell pwd) PROVIDER_NAME=$(PKG_NAME)
generate-docs:
go run scripts/generate-docs.go

website-test:
ifeq (,$(wildcard $(GOPATH)/src/$(WEBSITE_REPO)))
echo "$(WEBSITE_REPO) not found in your GOPATH (necessary for layouts and assets), get-ting..."
git clone https://$(WEBSITE_REPO) $(GOPATH)/src/$(WEBSITE_REPO)
endif
go run "scripts/website/parse-templates.go"
@$(MAKE) -C $(GOPATH)/src/$(WEBSITE_REPO) website-provider-test PROVIDER_PATH=$(shell pwd) PROVIDER_NAME=$(PKG_NAME)

.PHONY: build test testacc vet fmt fmtcheck errcheck test-compile website website-test
validate-docs:
tfplugindocs validate

.PHONY: build test testacc vet fmt fmtcheck errcheck test-compile validate-docs generate-docs
45 changes: 21 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,17 @@
Terraform Provider
==================
# Fastly Terraform Provider

- Website: https://www.terraform.io
- Documentation: https://registry.terraform.io/providers/fastly/fastly/latest/docs
- Mailing list: http://groups.google.com/group/terraform-tool
- [![Gitter chat](https://badges.gitter.im/hashicorp-terraform/Lobby.png)](https://gitter.im/hashicorp-terraform/Lobby)
- Mailing list: [Google Groups](http://groups.google.com/group/terraform-tool)

<img src="https://cdn.rawgit.com/hashicorp/terraform-website/master/content/source/assets/images/logo-hashicorp.svg" width="600px">

Requirements
------------

- [Terraform](https://www.terraform.io/downloads.html) 0.10.x
- [Go](https://golang.org/doc/install) 1.14 (to build the provider plugin)

Building The Provider
---------------------
## Building The Provider

Clone repository to: `$GOPATH/src/github.com/fastly/terraform-provider-fastly`

Expand All @@ -30,12 +27,7 @@ $ cd $GOPATH/src/github.com/fastly/terraform-provider-fastly
$ make build
```

Using the provider
----------------------
## Fill in for each provider

Developing the Provider
---------------------------
## Developing the Provider

If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.14+ is *required*).

Expand Down Expand Up @@ -83,21 +75,26 @@ In order to run the tests with extra debugging context, prefix the `make` comman
$ TF_LOG=trace make testacc
```

Building The Documentation
--------------------------
## Building The Documentation

The documentation is built from components (go templates) stored in the `website_src` folder.
Building the documentation copies the full markdown into the `website` folder, ready for deployment to Hashicorp.
The documentation is built from components (go templates) stored in the `templates` folder.
Building the documentation copies the full markdown into the `docs` folder, ready for deployment to Hashicorp.

With the repository cloned to: `$GOPATH/src/github.com/fastly/terraform-provider-fastly`:
> NOTE: you'll need the [`tfplugindocs`](https://github.com/hashicorp/terraform-plugin-docs) tool for generating the Markdown to be deployed to Hashicorp. For more information on generating documentation, refer to https://www.terraform.io/docs/registry/providers/docs.html

* To build the documentation:
`go run scripts/website/parse-templates.go `
* To validate the `/template` directory structure:
```
make validate-docs
```

* To build the `/docs` documentation Markdown files:
```
make generate-docs
```

* To build and preview the documentation online:
`make website`
* To view the documentation:
Paste `/docs` Markdown file content into https://registry.terraform.io/tools/doc-preview

Contributing
--------------------------
## Contributing

Refer to [CONTRIBUTING.md](./CONTRIBUTING.md)
Original file line number Diff line number Diff line change
Expand Up @@ -22,15 +22,21 @@ resource "aws_security_group" "from_fastly" {
from_port = "443"
to_port = "443"
protocol = "tcp"
cidr_blocks = data.fastly_ip_ranges.fastly.cidr_blocks
ipv6_cidr_blocks = data.fastly_ip_ranges.fastly.ipv6_cidr_blocks
cidr_blocks = ["${data.fastly_ip_ranges.fastly.cidr_blocks}"]
ipv6_cidr_blocks = ["${data.fastly_ip_ranges.fastly.ipv6_cidr_blocks}"]
}
}
```

## Attributes Reference
[1]: https://docs.fastly.com/guides/securing-communications/accessing-fastlys-ip-ranges
<!-- schema generated by tfplugindocs -->
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is currently some overlap between our own curated "Attributes Reference" and the "Schema" section generated dynamically by the new tfplugindocs tool, but until the issue (hashicorp/terraform-plugin-docs#28) is resolved we might want to hold off making any further content changes.

Copy link
Collaborator Author

@Integralist Integralist Jan 27, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After discussing with @phamann I've decided I'm going to review each individual file and manually decide whether the curated content should stay or go. This is because some of the generated documentation files have dynamically generated Schema data that is very good and ends up making our own "Arguments Reference" and "Attributes Reference" sections completely redundant (i.e. lots of duplication).

## Schema

* `cidr_blocks` - The lexically ordered list of ipv4 CIDR blocks.
* `ipv6_cidr_blocks` - The lexically ordered list of ipv6 CIDR blocks.
### Optional

[1]: https://docs.fastly.com/guides/securing-communications/accessing-fastlys-ip-ranges
- **id** (String) The ID of this resource.

### Read-only

- **cidr_blocks** (List of String) The lexically ordered list of ipv4 CIDR blocks.
- **ipv6_cidr_blocks** (List of String) The lexically ordered list of ipv6 CIDR blocks.
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: |-
Get information on Fastly WAF rules.
---

-> **Note:** This data source is only available from x.x.x of the Fastly terraform provider.
-> **Note:** This data source is only available from 0.20.0 of the Fastly terraform provider.

# fastly_waf_rules

Expand Down Expand Up @@ -125,6 +125,8 @@ resource "fastly_service_waf_configuration" "waf" {
}
```



## Argument Reference

~> **Warning:** The data source's filters are applied using an **AND** boolean operator, so depending on the combination of filters, they may become mutually exclusive.
Expand All @@ -145,4 +147,27 @@ The `rules` block supports:
* `latest_revision_number` - The rule's latest revision.
* `type` - The rule's type.

[1]: https://docs.fastly.com/api/ngwaf#ngwaf_rules
[1]: https://developer.fastly.com/reference/api/waf/rules/

<!-- schema generated by tfplugindocs -->
## Schema

### Optional

- **exclude_modsec_rule_ids** (List of Number) A list of modsecurity rules IDs to be excluded from the data set.
- **id** (String) The ID of this resource.
- **publishers** (List of String) A list of publishers to be used as filters for the data set.
- **tags** (List of String) A list of tags to be used as filters for the data set.

### Read-only

- **rules** (List of Object) The list of rules that results from any given combination of filters. (see [below for nested schema](#nestedatt--rules))

<a id="nestedatt--rules"></a>
### Nested Schema for `rules`

Read-only:

- **latest_revision_number** (Number)
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are a few issues open already with the tfplugindocs tool only just being release. I've opened an issue related to nested Schema 'Description' fields not being included in the output.

hashicorp/terraform-plugin-docs#28

- **modsec_rule_id** (Number)
- **type** (String)
6 changes: 2 additions & 4 deletions website/docs/index.html.markdown → docs/index.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
---
layout: "fastly"
page_title: "Provider: Fastly"
sidebar_current: "docs-fastly-index"
page_title: "fastly Provider"
subcategory: ""
description: |-
Fastly
---

# Fastly Provider
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ resource "fastly_service_acl_entries_v1" "entries" {
}
```

## Example Usage (Terraform >= 0.12.0 && < 0.12.6)
## Example Usage (Terraform >= 0.12.0 && &lt; 0.12.6)

`for_each` attributes were not available in Terraform before 0.12.6, however, users can still use `for` expressions to achieve
similar behaviour as seen in the example below.
Expand Down Expand Up @@ -199,24 +199,6 @@ resource "fastly_service_acl_entries_v1" "entries" {
}
```


## Argument Reference

The following arguments are supported:

* `service_id` - (Required) The ID of the Service that the ACL belongs to
* `acl_id` - (Required) The ID of the ACL that the items belong to
* `entry` - (Optional) A Set ACL entries that are applied to the service. Defined below

The `entry` block supports:

* `ip` - (Required, string) An IP address that is the focus for the ACL
* `subnet` - (Optional, string) An optional subnet mask applied to the IP address
* `negated` - (Optional, boolean) A boolean that will negate the match if true
* `comment` - (Optional, string) A personal freeform descriptive note



## Attributes Reference

* [fastly-acl](https://developer.fastly.com/reference/api/acls/acl/)
Expand All @@ -237,3 +219,33 @@ The following is an example of the Terraform state command to remove the resourc
```
$ terraform state rm fastly_service_acl_entries_v1.entries
```

<!-- schema generated by tfplugindocs -->
## Schema

### Required

- **acl_id** (String) The ID of the ACL that the items belong to
- **service_id** (String) The ID of the Service that the ACL belongs to

### Optional

- **entry** (Block Set, Max: 10000) (see [below for nested schema](#nestedblock--entry))
- **id** (String) The ID of this resource.

<a id="nestedblock--entry"></a>
### Nested Schema for `entry`

Required:

- **ip** (String) An IP address that is the focus for the ACL

Optional:

- **comment** (String) A personal freeform descriptive note
- **negated** (Boolean) A boolean that will negate the match if true
- **subnet** (String) An optional subnet mask applied to the IP address

Read-only:

- **id** (String) The ID of this resource.
Loading