Merge pull request #20 from antonlindstrom/feature/testable-example

Add testable example in README

.travis.yml

@@ -5,9 +5,13 @@ go:
   - 1.6
   - tip
 
-script:
+install:
   - make get-deps
+  - go get github.com/campoy/embedmd
+
+script:
   - make metalint
+  - make docs-check
   - make check
 
 env:

Makefile

@@ -9,7 +9,7 @@ get-deps:
 	go get -v ./...
 
 .PHONY: test
-test: get-deps metalint check
+test: get-deps metalint docs-check check
 
 .PHONY: check
 check:
@@ -29,7 +29,7 @@ docker-test:
 	docker run -d -p 5432:5432 --name=pgstore_test_1 postgres:9.4
 	sleep 5
 	docker run --rm --link pgstore_test_1:postgres postgres:9.4 psql -c 'create database test;' -U postgres -h postgres
-	PGSTORE_TEST_CONN="postgres://postgres@127.0.0.1:5432/test?sslmode=disable" make check
+	PGSTORE_TEST_CONN="postgres://postgres@127.0.0.1:5432/test?sslmode=disable" make test
 	docker kill pgstore_test_1
 	docker rm pgstore_test_1
 
@@ -37,3 +37,15 @@ docker-test:
 docker-clean:
 	-docker kill pgstore_test_1
 	-docker rm pgstore_test_1
+
+.PHONY: docs-dep
+	which embedmd > /dev/null || go get github.com/campoy/embedmd
+
+.PHONY: docs-check
+docs-check: docs-dep
+	@echo "Checking if docs are generated, if this fails, run 'make docs'."
+	embedmd README.md | diff README.md -
+
+.PHONY: docs
+docs: docs-dep
+	embedmd -w README.md

README.md

@@ -14,34 +14,49 @@ See http://www.gorillatoolkit.org/pkg/sessions for full documentation on underly
 
 ### Example
 
+[embedmd]:# (examples/sessions.go)
 ```go
-// Fetch new store.
-store, err := NewPGStore("postgres://user:password@127.0.0.1:5432/database?sslmode=verify-full", []byte("secret-key"))
-if err != nil {
-    log.Error(err.Error())
-}
-defer store.Close()
-// Run a background goroutine to clean up expired sessions from the database.
-defer store.StopCleanup(store.Cleanup(time.Minute * 5))
+package examples
 
-// Get a session.
-session, err = store.Get(req, "session-key")
-if err != nil {
-    log.Error(err.Error())
-}
+import (
+	"log"
+	"net/http"
+	"time"
 
-// Add a value.
-session.Values["foo"] = "bar"
+	"github.com/antonlindstrom/pgstore"
+)
 
-// Save.
-if err = sessions.Save(req, rsp); err != nil {
-    t.Fatalf("Error saving session: %v", err)
-}
+// ExampleHandler is an example that displays the usage of PGStore.
+func ExampleHandler(w http.ResponseWriter, r *http.Request) {
+	// Fetch new store.
+	store, err := pgstore.NewPGStore("postgres://user:password@127.0.0.1:5432/database?sslmode=verify-full", []byte("secret-key"))
+	if err != nil {
+		log.Fatalf(err.Error())
+	}
+	defer store.Close()
 
-// Delete session.
-session.Options.MaxAge = -1
-if err = sessions.Save(req, rsp); err != nil {
-    t.Fatalf("Error saving session: %v", err)
+	// Run a background goroutine to clean up expired sessions from the database.
+	defer store.StopCleanup(store.Cleanup(time.Minute * 5))
+
+	// Get a session.
+	session, err := store.Get(r, "session-key")
+	if err != nil {
+		log.Fatalf(err.Error())
+	}
+
+	// Add a value.
+	session.Values["foo"] = "bar"
+
+	// Save.
+	if err = session.Save(r, w); err != nil {
+		log.Fatalf("Error saving session: %v", err)
+	}
+
+	// Delete session.
+	session.Options.MaxAge = -1
+	if err = session.Save(r, w); err != nil {
+		log.Fatalf("Error saving session: %v", err)
+	}
 }
 ```
 

examples/sessions.go

@@ -0,0 +1,42 @@
+package examples
+
+import (
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/antonlindstrom/pgstore"
+)
+
+// ExampleHandler is an example that displays the usage of PGStore.
+func ExampleHandler(w http.ResponseWriter, r *http.Request) {
+	// Fetch new store.
+	store, err := pgstore.NewPGStore("postgres://user:password@127.0.0.1:5432/database?sslmode=verify-full", []byte("secret-key"))
+	if err != nil {
+		log.Fatalf(err.Error())
+	}
+	defer store.Close()
+
+	// Run a background goroutine to clean up expired sessions from the database.
+	defer store.StopCleanup(store.Cleanup(time.Minute * 5))
+
+	// Get a session.
+	session, err := store.Get(r, "session-key")
+	if err != nil {
+		log.Fatalf(err.Error())
+	}
+
+	// Add a value.
+	session.Values["foo"] = "bar"
+
+	// Save.
+	if err = session.Save(r, w); err != nil {
+		log.Fatalf("Error saving session: %v", err)
+	}
+
+	// Delete session.
+	session.Options.MaxAge = -1
+	if err = session.Save(r, w); err != nil {
+		log.Fatalf("Error saving session: %v", err)
+	}
+}