doc: Adopters list in README (#252)

Adds a list of most popular projects using avo, based on Github Stars.

Auto-generated from the third-party packages list using docgen.

Updates #101

README.md

@@ -187,6 +187,46 @@ Implementations of full algorithms:
 * **[geohash](examples/geohash):** Integer [geohash](https://en.wikipedia.org/wiki/Geohash) encoding.
 * **[stadtx](examples/stadtx):** [`StadtX` hash](https://github.com/demerphq/BeagleHash) port from [dgryski/go-stadtx](https://github.com/dgryski/go-stadtx).
 
+## Adopters
+
+Popular projects using `avo`:
+
+<img src="https://github.com/klauspost.png?size=24" width="24" height="24" hspace="4" valign="middle" /> [klauspost / **compress**](https://github.com/klauspost/compress) / **s2**
+:star: 2702
+> Optimized Go Compression Packages
+
+<img src="https://github.com/golang.png?size=24" width="24" height="24" hspace="4" valign="middle" /> [golang / **crypto**](https://github.com/golang/crypto) / **curve25519**
+:star: 2391
+> [mirror] Go supplementary cryptography libraries
+
+<img src="https://github.com/klauspost.png?size=24" width="24" height="24" hspace="4" valign="middle" /> [klauspost / **reedsolomon**](https://github.com/klauspost/reedsolomon)
+:star: 1428
+> Reed-Solomon Erasure Coding in Go
+
+<img src="https://github.com/segmentio.png?size=24" width="24" height="24" hspace="4" valign="middle" /> [segmentio / **asm**](https://github.com/segmentio/asm)
+:star: 681
+> Go library providing algorithms optimized to leverage the characteristics of modern CPUs
+
+<img src="https://github.com/zeebo.png?size=24" width="24" height="24" hspace="4" valign="middle" /> [zeebo / **blake3**](https://github.com/zeebo/blake3)
+:star: 288
+> Pure Go implementation of BLAKE3 with AVX2 and SSE4.1 acceleration
+
+<img src="https://github.com/lukechampine.png?size=24" width="24" height="24" hspace="4" valign="middle" /> [lukechampine / **blake3**](https://github.com/lukechampine/blake3)
+:star: 278
+> A pure-Go implementation of the BLAKE3 cryptographic hash function
+
+<img src="https://github.com/zeebo.png?size=24" width="24" height="24" hspace="4" valign="middle" /> [zeebo / **xxh3**](https://github.com/zeebo/xxh3)
+:star: 235
+> XXH3 algorithm in Go
+
+<img src="https://github.com/dgryski.png?size=24" width="24" height="24" hspace="4" valign="middle" /> [dgryski / **go-bloomindex**](https://github.com/dgryski/go-bloomindex)
+:star: 111
+> Bloom-filter based search index
+
+<img src="https://github.com/minio.png?size=24" width="24" height="24" hspace="4" valign="middle" /> [minio / **md5-simd**](https://github.com/minio/md5-simd)
+:star: 107
+> Accelerate aggregated MD5 hashing performance up to 8x for AVX512 and 4x for AVX2. Useful for server applications that need to compute many MD5 sums in parallel.
+
 ## Contributing
 
 Contributions to `avo` are welcome:

internal/cmd/docgen/main.go

@@ -14,6 +14,8 @@ import (
 	"regexp"
 	"strings"
 	"text/template"
+
+	"github.com/mmcloughlin/avo/tests/thirdparty"
 )
 
 func main() {
@@ -25,9 +27,10 @@ func main() {
 }
 
 var (
-	typ    = flag.String("type", "", "documentation type")
-	tmpl   = flag.String("tmpl", "", "explicit template file (overrides -type)")
-	output = flag.String("output", "", "path to output file (default stdout)")
+	typ          = flag.String("type", "", "documentation type")
+	tmpl         = flag.String("tmpl", "", "explicit template file (overrides -type)")
+	output       = flag.String("output", "", "path to output file (default stdout)")
+	pkgsfilename = flag.String("pkgs", "", "packages configuration")
 )
 
 func mainerr() (err error) {
@@ -51,9 +54,23 @@ func mainerr() (err error) {
 		return err
 	}
 
+	// Load third-party packages.
+	if *pkgsfilename == "" {
+		return errors.New("missing packages configuration")
+	}
+
+	pkgs, err := thirdparty.LoadPackagesFile(*pkgsfilename)
+	if err != nil {
+		return err
+	}
+
 	// Execute.
+	data := map[string]interface{}{
+		"Packages": pkgs,
+	}
+
 	var buf bytes.Buffer
-	if err := t.Execute(&buf, nil); err != nil {
+	if err := t.Execute(&buf, data); err != nil {
 		return err
 	}
 	body := buf.Bytes()

internal/cmd/docgen/templates/readme.tmpl

@@ -100,6 +100,19 @@ Implementations of full algorithms:
 * **[geohash](examples/geohash):** Integer [geohash](https://en.wikipedia.org/wiki/Geohash) encoding.
 * **[stadtx](examples/stadtx):** [`StadtX` hash](https://github.com/demerphq/BeagleHash) port from [dgryski/go-stadtx](https://github.com/dgryski/go-stadtx).
 
+## Adopters
+
+Popular projects using `avo`:
+
+{{ range .Packages.Top 10 -}}
+{{ if lt .Metadata.Stars 100 }}{{break}}{{ end -}}
+<img src="https://github.com/{{ .Repository.Owner }}.png?size=24" width="24" height="24" hspace="4" valign="middle" /> [{{ .Repository.Owner }} / **{{ .Repository.Name }}**]({{ .Repository.URL }})
+{{- if .SubPackage }} / **{{ .SubPackage}}**{{ end }}
+:star: {{ .Metadata.Stars }}
+> {{ .Metadata.Description }}
+
+{{ end -}}
+
 ## Contributing
 
 Contributions to `avo` are welcome:

script/doc

@@ -3,7 +3,8 @@
 # Generate some specific files with docgen.
 go install ./internal/cmd/docgen
 
-docgen -type readme -output README.md
+pkgs="tests/thirdparty/packages.json"
+docgen -pkgs "${pkgs}" -type readme -output README.md
 
 # Process simple file embeddings with embedmd.
 find . -name '*.md' | xargs embedmd -w

tests/thirdparty/config.go

@@ -9,6 +9,7 @@ import (
 	"os"
 	"path"
 	"path/filepath"
+	"sort"
 	"strings"
 )
 
@@ -22,6 +23,11 @@ func (r GithubRepository) String() string {
 	return path.Join(r.Owner, r.Name)
 }
 
+// URL returns the Github repository URL.
+func (r GithubRepository) URL() string {
+	return fmt.Sprintf("https://github.com/%s", r)
+}
+
 // CloneURL returns the git clone URL.
 func (r GithubRepository) CloneURL() string {
 	return fmt.Sprintf("https://github.com/%s.git", r)
@@ -256,6 +262,25 @@ func (p Packages) Validate() error {
 	return nil
 }
 
+// Ranked returns a copy of the packages list ranked in desending order of
+// popularity.
+func (p Packages) Ranked() Packages {
+	ranked := append(Packages(nil), p...)
+	sort.SliceStable(ranked, func(i, j int) bool {
+		return ranked[i].Metadata.Stars > ranked[j].Metadata.Stars
+	})
+	return ranked
+}
+
+// Top returns the top n most popular packages.
+func (p Packages) Top(n int) Packages {
+	top := p.Ranked()
+	if len(top) > n {
+		top = top[:n]
+	}
+	return top
+}
+
 // LoadPackages loads a list of package configurations from JSON format.
 func LoadPackages(r io.Reader) (Packages, error) {
 	var pkgs Packages