improve API for mumax3.10

doc/.gitignore

@@ -1,5 +1,2 @@
-*.mx3
-*.out
-examples.html
-api.html
-doc
+build
+doc

doc/Makefile

@@ -1,18 +1,22 @@
+BUILDDIR="build"
+STATIC="static"
+
+# build the html pages in ${BUILDDIR}
+.PHONY: html
+html: doc mumax3libs
+	mkdir -p ${BUILDDIR}
+	./doc -examples -builddir ${BUILDDIR}
+	cp ${STATIC}/* build
+
 .PHONY: doc
 doc:
 	go build -v
 
-.PHONY: html
-html: doc
+.PHONY: mumax3libs
+mumax3libs:
 	go install -v github.com/mumax/3/cmd/...
-	./doc -vet 2> /dev/null || echo no worries
-	./doc
 
 .PHONY: clean
 clean:
-	rm -rf example*.out example*.mx3
-	rm -f doc
-
-.PHONY: realclean
-realclean: clean
-	rm -f api.html examples.html
+	rm -rf build
+	rm -f doc

doc/README

@@ -0,0 +1,3 @@
+This directory contains everything needed to build the mumax3 website (Home page, API, and examples)
+
+"make html" builds the complete website in ${BUILDDIR}.

doc/apigen.go

@@ -5,6 +5,7 @@ import (
 	"io/ioutil"
 	"os"
 	"os/exec"
+	"path"
 	"reflect"
 	"sort"
 	"strings"
@@ -52,7 +53,9 @@ func getGoDocString(packageName, identifier string) string {
 	cmd := exec.Command("go", "doc", packageName, identifier)
 	stdout, err := cmd.Output()
 	if err == nil && string(stdout)[:4] == "func" { // we only look for doc strings of functions
-		docString = strings.SplitAfterN(string(stdout), "\n", 3)[1] // the doc string of a function is on the second line
+		// the doc string of a function is on the second line
+		// (and possible continued on the third line, if not, then the third line is empty)
+		docString = strings.Join(strings.SplitAfterN(string(stdout), "\n", 4)[1:3], " ")
 	}
 	return docString
 }
@@ -132,7 +135,7 @@ type api struct {
 
 // include file
 func (e *api) Include(fname string) string {
-	b, err := ioutil.ReadFile(fname)
+	b, err := ioutil.ReadFile(path.Join(templateDir, fname))
 	check(err)
 	return string(b)
 }
@@ -160,7 +163,7 @@ func (a *api) All() []*entry {
 // return all entries, unused so far, which have given type.
 func (a *api) FilterType(typ ...string) []*entry {
 	var E []*entry
-	for _, e := range a.remaining() {
+	for _, e := range a.Entries {
 		for _, t := range typ {
 			if match(t, e.Type.String()) &&
 				!strings.HasPrefix(e.name, "ext_") {
@@ -175,7 +178,7 @@ func (a *api) FilterType(typ ...string) []*entry {
 // return all entries, unused so far, which have given return type.
 func (a *api) FilterReturn(typ ...string) []*entry {
 	var E []*entry
-	for _, e := range a.remaining() {
+	for _, e := range a.Entries {
 		for _, t := range typ {
 			if match(t, e.Ret()) &&
 				!strings.HasPrefix(e.name, "ext_") {
@@ -190,7 +193,7 @@ func (a *api) FilterReturn(typ ...string) []*entry {
 // return all entries, unused so far, which have given name.
 func (a *api) FilterName(typ ...string) []*entry {
 	var E []*entry
-	for _, e := range a.remaining() {
+	for _, e := range a.Entries {
 		for _, t := range typ {
 			if match(t, e.name) &&
 				!strings.HasPrefix(e.name, "ext_") {
@@ -205,7 +208,7 @@ func (a *api) FilterName(typ ...string) []*entry {
 // return all entries, unused so far, whose name starts with prefix.
 func (a *api) FilterPrefix(pre string) []*entry {
 	var E []*entry
-	for _, e := range a.remaining() {
+	for _, e := range a.Entries {
 		if strings.HasPrefix(e.name, pre) {
 			e.touched = true
 			E = append(E, e)
@@ -230,12 +233,12 @@ func match(a, b string) bool {
 func renderAPI() {
 	e := api_entries
 	t := template.Must(template.New("api").Parse(templ))
-	f, err2 := os.OpenFile("api.html", os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0666)
+	f, err2 := os.OpenFile(path.Join(buildDir, "api.html"), os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0666)
 	check(err2)
 	check(t.Execute(f, &api{e}))
 }
 
-var templ = read("api-template.html")
+var templ = read(path.Join(templateDir, "api-template.html"))
 
 func read(fname string) string {
 	b, err := ioutil.ReadFile(fname)

doc/make.go

@@ -15,30 +15,51 @@ import (
 )
 
 var flag_vet = flag.Bool("vet", false, "only vet source files, don't run them")
-var flag_api = flag.Bool("api", false, "only generate API")
+var flag_examples = flag.Bool("examples", false, "run mumax3 examples")
+var flag_forced = flag.Bool("forced", false, "force to re-run mumax3 examples")
+var flag_builddir = flag.String("builddir", "build", "build directory")
+
+var buildDir string
+
+const templateDir = "templates"
 
 func main() {
+
 	flag.Parse()
+	buildDir = *flag_builddir + "/"
 
 	buildAPI()
 
 	// read template
-	b, err := ioutil.ReadFile("template.html")
+	b, err := ioutil.ReadFile(path.Join(templateDir, "examples-template.html"))
 	check(err)
 	replaceInRaw(b, '\n', '@') // hack to allow raw strings spanning multi lines
 	templ := template.Must(template.New("guide").Parse(string(b)))
 
 	// output file
-	f, err2 := os.OpenFile("examples.html", os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0666)
+	f, err2 := os.OpenFile(path.Join(buildDir, "examples.html"), os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0666)
 	check(err2)
 
 	// execute!
-	if !*flag_api {
+	if *flag_examples {
 		state := &State{}
 		check(templ.Execute(f, state))
 	}
 
 	renderAPI()
+
+	createIndexPage()
+}
+
+func createIndexPage() {
+	b, err := ioutil.ReadFile(path.Join(templateDir, "index-template.html"))
+	replaceInRaw(b, '\n', '@') // hack to allow raw strings spanning multi lines
+	check(err)
+	templ := template.Must(template.New("guid").Parse(string(b)))
+	f, err2 := os.OpenFile(path.Join(buildDir, "index.html"), os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0666)
+	check(err2)
+	state := &State{}
+	check(templ.Execute(f, state))
 }
 
 type State struct {
@@ -58,7 +79,10 @@ func (s *State) Example(in string) string {
 	if *flag_vet {
 		arg = "-vet"
 	}
-	cmd("mumax3", "-cache", "/tmp", arg, s.infile())
+
+	if _, err := os.Stat(s.outfile()); os.IsNotExist(err) || *flag_forced {
+		cmd("mumax3", "-cache", "/tmp", arg, s.infile())
+	}
 
 	recordExamples(in, s.count)
 
@@ -77,8 +101,8 @@ func recordExamples(input string, num int) {
 }
 
 func (s *State) Img(fname string) string {
-	cmd("mumax3-convert", "-png", "-arrows", "16", s.outfile()+"/"+fname+".ovf")
-	pngfile := s.outfile() + "/" + fname + ".png"
+	cmd("mumax3-convert", "-png", "-arrows", "16", path.Join(s.outfile(), fname+".ovf"))
+	pngfile := path.Join(s.relativeOutfile(), fname+".png")
 	return fmt.Sprintf(`
 <figure style="float:left">
 	<img src="%v"/>
@@ -87,7 +111,7 @@ func (s *State) Img(fname string) string {
 }
 
 func (s *State) Include(fname string) string {
-	b, err := ioutil.ReadFile(fname)
+	b, err := ioutil.ReadFile(path.Join(templateDir, fname))
 	check(err)
 	return string(b)
 }
@@ -109,7 +133,7 @@ func (s *State) Output() string {
 
 	for _, f := range files {
 		if f == "table.txt" {
-			cmd("mumax3-plot", s.outfile()+"/"+f)
+			cmd("mumax3-plot", path.Join(s.outfile(), f))
 		}
 	}
 
@@ -120,7 +144,7 @@ func (s *State) Output() string {
 	sort.Strings(files)
 	for _, f := range files {
 		if path.Ext(f) == ".svg" {
-			src := s.outfile() + "/" + f
+			src := path.Join(s.relativeOutfile(), f)
 			out += fmt.Sprintf(`
 <figure>
 	<img src="%v"/>
@@ -135,8 +159,9 @@ func (s *State) Output() string {
 // hysteresis example. State.OutputHysteresis is the custom output function
 // for the hysteresis example.
 func (s *State) OutputHysteresis() string {
-	tableName := fmt.Sprintf(`%s/table.txt`, s.outfile())
-	figureName := fmt.Sprintf(`%s/hysteresis.svg`, s.outfile())
+	tableName := path.Join(s.outfile(), "table.txt")
+	figureName := path.Join(s.outfile(), "hysteresis.svg")
+	relFigureName := path.Join(s.relativeOutfile(), "hysteresis.svg")
 
 	gnuplotCmd := `set term svg noenhanced size 400 300 font 'Arial,10';`
 	gnuplotCmd += fmt.Sprintf(`set output "%s";`, figureName)
@@ -153,16 +178,21 @@ func (s *State) OutputHysteresis() string {
 <h3>output</h3>
 <figure>
 	<img src="%v"/>
-</figure>`, figureName)
+</figure>`, relFigureName)
 
 	return out
 }
 
 func (s *State) infile() string {
-	return fmt.Sprintf("example%v.mx3", s.count)
+	return path.Join(buildDir, fmt.Sprintf("example%v.mx3", s.count))
 }
 
 func (s *State) outfile() string {
+	return path.Join(buildDir, fmt.Sprintf("example%v.out", s.count))
+}
+
+// Relative output directory path from the build directory
+func (s *State) relativeOutfile() string {
 	return fmt.Sprintf("example%v.out", s.count)
 }