Improve README organization (put higher level usage first), make docs friendlier for newcomers to Go.

[coolaj86]

I'm relatively new to writing go and I've never used a go vfs before. From the research I've done it sounds like fileb0x and vfsgen are among the best options.

The docs look really good, but I'm missing some critical pieces of information. I can't quite grok it with my limited knowledge.

Is there a blog or screencast or something that could walk me through step by step on how to use this as someone who is uninitiated?

I'm looking for something that I imagine would look like this:

What I Imagine What I Need Would Look Like

Obviously some of the stuff below is bogus (because I don't understand entirely what I need to do), but something similar to this is what I imagine.

Step 1: Create your main.go

main.go:

package main

import (
  "fmt"

  "https://github.com/shurcooL/vfsgen"
)

func main() {
  vfs := vfsgen.Folder("dist")
  fmt.Println(vfs.Read("/hello.txt"))

  gzipfile, err := vfs.ReadGzip("/lotsoftext.txt")
  if nil != err {
    panic("expected text file with lots of text to be compressed")
  }

  pngfile, err := vfs.ReadGzip("/favicon.png")
  if nil != err {
    panic("didn't expect gzipped png - it's already gzipped anyway!")
  } else {
    pngfile, err = vfs.ReadBytes("/favicon.png")
  }
}

Step 2: Create you dist folder and the files you want

./dist/

hello.txt
favicon.png
lotsofwords.txt
dir1/goodbye.txt

Note: any files or directories listed in .vfsignore will not be included.

Step 3: Create the meta go generate file

assets_generate.go

//go:generate run --dostuff vfsgen --someopts
package main // must match main.go, main.go imports will be rewritten accordingly

func __VFS_GEN__() {
  vfs.Pack("dist", "dist");
  vfs.Pack("../../otherthing", "redthing");
}

Step 4: build your stuff

go generate assets_generate.go
go build -o helloFromFile main.go

[dmitshur]

Hi @coolaj86. Thank you for checking out vfsgen, and for filing a detailed issue.

You're absolutely right. vfsgen documentation is currently not great, especially for newcomers to Go. It explains things at a very low level and assumes you're already very familiar with the http.FileSystem interface.

This happened because I created this package a very long time ago, after I already had a lot of familiarity and experience with the field of embedding data into Go binaries, and I wanted to create a very specific solution to address my needs. As time went on, I discovered and created higher level tools, and those got added to the bottom of the README.

I realize now that the low-level internal details should be pushed further away, and vfsgendev and its usage should be the first thing new users see and get exposed to.

It'd also be a great idea to have a blog post or a tutorial that covers a little more than the README would; unfortunately I haven't created one yet.

I'd like to improve this and make vfsgen and vfsgendev more accessible, even to newcomers to Go. I'll use this issue to track that task. I'll answer your specific question in PR #56 you sent.

[a-h]

It took me a while to work out how to use the tool, and I gave up once before.

Here's the main.go file I run to package up some JSON schema files in the ./schema directory into the ./schema/schema.go file.

It's probably simpler than having to cover how go generate works. You just run the main.go instead.

package main

import (
	"log"
	"net/http"
	"os"

	"github.com/shurcooL/vfsgen"
)

var fs http.FileSystem = http.Dir("./schema")

func main() {
	// Delete the old file.
	os.Remove("./schema/schema.go")
	err := vfsgen.Generate(fs, vfsgen.Options{
		Filename:        "./schema/schema.go",
		PackageName:     "schema",
		VariableName:    "Assets",
		VariableComment: "Assets contains JSON schema.",
	})
	if err != nil {
		log.Fatalln(err)
	}
}

Then, I can use schema.Assets.Open() to get the content.

[matthewmueller]

+1, this project is super handy, but it also took me a while to figure out what was going on.

The way I'd approach the readme is similar to @a-h.

1. How to run this in development (based on @a-h example above)
2. How to compile it for production

And I'd reserve build tags, go:generate, precompiling with the CLI for more advanced configurations.

Something like this would be great for starters!

package main

import (
	"flag"
	"net/http"

	"github.com/shurcooL/vfsgen"
)

func main() {
	var dev = flag.Bool("dev", false, "development")
	flag.Parse()

	var fs http.FileSystem
	if *dev {
		fs = http.Dir("./static")
		if err := vfsgen.Generate(fs, vfsgen.Options{
			PackageName:  "main",
			VariableName: "Assets",
		}); err != nil {
			panic(err)
		}
	} else {
		fs = Assets
	}

}

---

Unrelated sidenote: the little arabic character for doing namespaced identifiers is awesome!! e.g. vfsgen۰FS