From 18a119b0c27cf54295623ebc0c09789c6472fc89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20de=20la=20Pe=C3=B1a?= Date: Fri, 23 Dec 2022 08:07:19 +0100 Subject: [PATCH] docs: refine onboarding process with quickstart guide (#706) * docs: move OSS to license section * docs: move quickstart page to root dir * docs: link quickstart in the index * docs: tidy up quickstart guide * docs: link Redis example in the quickstart guide * docs: rephrase link to docs in README * docs: link to quickstart in the main README * fix: proper link * fix: update mkdocs struct * fix: typo --- README.md | 7 ++++-- docs/index.md | 6 ++--- docs/{quickstart/gotest.md => quickstart.md} | 26 ++++++++++++-------- examples/mkdocs.go | 2 +- mkdocs.yml | 3 +-- 5 files changed, 26 insertions(+), 18 deletions(-) rename docs/{quickstart/gotest.md => quickstart.md} (92%) diff --git a/README.md b/README.md index 5f0b59641e..3c2d6aa2f6 100644 --- a/README.md +++ b/README.md @@ -6,5 +6,8 @@ _Testcontainers for Go_ is a Go package that makes it simple to create and clean automated integration/smoke tests. The clean, easy-to-use API enables developers to programmatically define containers that should be run as part of a test and clean up those resources when the test is done. -You can find more information about _Testcontainers for Go_ in the [./docs](./docs) directory, which is rendered at -[golang.testcontainers.org](https://golang.testcontainers.org). +You can find more information about _Testcontainers for Go_ at [golang.testcontainers.org](https://golang.testcontainers.org), which is rendered from the [./docs](./docs) directory. + +## Using _Testcontainers for Go_ + +Please visit [the quickstart guide](https://golang.testcontainers.org/quickstart) to understand how to add the dependency to your Go project. diff --git a/docs/index.md b/docs/index.md index a188e17014..b2205f4bf9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,8 +18,7 @@ _Testcontainers for Go_ is a Go package that makes it simple to create and clean automated integration/smoke tests. The clean, easy-to-use API enables developers to programmatically define containers that should be run as part of a test and clean up those resources when the test is done. -This project is opensource and you can have a look at the code on -[GitHub](https://github.com/testcontainers/testcontainers-go). +To start using _Testcontainers for Go_ please read our [quickstart guide](./quickstart.md). ## GoDoc @@ -34,7 +33,8 @@ examples as well. Check it out at ## License -See [LICENSE](https://github.com/testcontainers/testcontainers-go/blob/main/LICENSE). +This project is opensource and you can have a look at the code on +[GitHub](https://github.com/testcontainers/testcontainers-go). See [LICENSE](https://github.com/testcontainers/testcontainers-go/blob/main/LICENSE). ## Copyright diff --git a/docs/quickstart/gotest.md b/docs/quickstart.md similarity index 92% rename from docs/quickstart/gotest.md rename to docs/quickstart.md index 843548bf15..706ae71d48 100644 --- a/docs/quickstart/gotest.md +++ b/docs/quickstart.md @@ -3,15 +3,11 @@ _Testcontainers for Go_ plays well with the native `go test` framework. The ideal use case is for integration or end to end tests. It helps you to spin up and manage the dependencies life cycle via Docker. -Docker has to be available for this library to work. +## 1. System requirements -## 1. Install +Please read the [system requirements](../system_requirements/) page before you start. -We use [gomod](https://blog.golang.org/using-go-modules) and you can get it installed via: - -``` -go get github.com/testcontainers/testcontainers-go -``` +## 2. Install _Testcontainers for Go_ !!!warning @@ -38,7 +34,13 @@ go get github.com/testcontainers/testcontainers-go ) ``` -## 2. Spin up Redis +We use [gomod](https://blog.golang.org/using-go-modules) and you can get it installed via: + +``` +go get github.com/testcontainers/testcontainers-go +``` + +## 3. Spin up Redis ```go import ( @@ -105,7 +107,7 @@ terminated function: `defer redisC.Terminate(ctx)`. Look at [features/garbage_collector](/features/garbage_collector/) to know another way to clean up resources. -## 3. Make your code to talk with the container +## 4. Make your code to talk with the container This is just an example, but usually Go applications that rely on Redis are using the [redis-go](https://github.com/go-redis/redis) client. This code gets @@ -133,6 +135,10 @@ We expose only one port, so the `Endpoint` does not need a second argument set. In this case it returns: `localhost:`. -## 3. Run the test +## 5. Run the test You can run the test via `go test ./...` + +## 6. Want to go deeper with Redis? + +You can find a more elaborated Redis example in our examples section. Please check it out [here](./examples/redis.md). diff --git a/examples/mkdocs.go b/examples/mkdocs.go index b550f57460..57a4b90d27 100644 --- a/examples/mkdocs.go +++ b/examples/mkdocs.go @@ -29,7 +29,7 @@ type MkDocsConfig struct { MarkdownExtensions []interface{} `yaml:"markdown_extensions"` Nav []struct { Home string `yaml:"Home,omitempty"` - Quickstart []string `yaml:"Quickstart,omitempty"` + Quickstart string `yaml:"Quickstart,omitempty"` Features []interface{} `yaml:"Features,omitempty"` Examples []string `yaml:"Examples,omitempty"` SystemRequirements []string `yaml:"System Requirements,omitempty"` diff --git a/mkdocs.yml b/mkdocs.yml index db3a255bed..4c6f5a9f60 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,8 +26,7 @@ markdown_extensions: - pymdownx.snippets nav: - Home: index.md - - Quickstart: - - quickstart/gotest.md + - Quickstart: quickstart.md - Features: - features/creating_container.md - features/networking.md