task: adding a bit more of content to the build command

cmd/doco/build.go

@@ -1,10 +1,20 @@
 package main
 
-import "github.com/paganotoni/doco/internal"
+import (
+	"errors"
+	"os"
+
+	"github.com/paganotoni/doco/internal"
+)
 
 // build generates the static html files for the site
 // and writes them to the destination folder.
 func build(src, dst string) error {
+	_, err := os.Stat(src)
+	if err != nil {
+		return errors.New("docs folder does not exist, aborting build")
+	}
+
 	site, err := internal.NewSite(src)
 	if err != nil {
 		return err

cmd/doco/main.go

@@ -45,7 +45,7 @@ func main() {
 	case "build":
 		err := build(docsFolder, dstFolder)
 		if err != nil {
-			fmt.Println(err)
+			fmt.Println("ERROR:", err)
 		}
 
 	case "init":
@@ -58,6 +58,9 @@ func main() {
 	case "help":
 		printHelp(os.Stdout)
 	case "serve":
+		build(docsFolder, dstFolder)
+
+		go watch(docsFolder, dstFolder)
 		serve()
 	default:
 		fmt.Printf("Unknown command %s\n", args[1])

cmd/doco/watch.go

@@ -0,0 +1,65 @@
+package main
+
+import (
+	"log"
+	"os"
+	"path/filepath"
+
+	"github.com/fsnotify/fsnotify"
+)
+
+// watch a folder for changes and rebuild the documentation
+// when a change is detected.
+func watch(docsFolder, dstFolder string) {
+	log.Println("> 👀 Watching for changes in", docsFolder)
+
+	watcher, err := fsnotify.NewWatcher()
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer watcher.Close()
+
+	// Start listening for events.
+	go func() {
+		for {
+			select {
+			case event, ok := <-watcher.Events:
+				if !ok {
+					return
+				}
+
+				if event.Has(fsnotify.Write) {
+					build(docsFolder, dstFolder)
+					log.Println(">", event.Name, "changed, documentation rebuilt.")
+				}
+			case err, ok := <-watcher.Errors:
+				if !ok {
+					return
+				}
+				log.Println("error:", err)
+			}
+		}
+	}()
+
+	// add the folder and its subfolders to the watcher by
+	// walking the folder.
+	err = filepath.Walk(docsFolder, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+
+		err = watcher.Add(path)
+		if err != nil {
+			return err
+		}
+
+		return nil
+	})
+
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Block main goroutine forever.
+	<-make(chan struct{})
+}

docs/The CLI/_meta.md → docs/the_cli/_meta.md

@@ -1,3 +1,4 @@
 ---
 index: 3
----
+---
+

docs/The CLI/build.md → docs/the_cli/build.md

@@ -7,8 +7,10 @@ Build generates the static documentation site from the markdown files in the `do
 
 ```sh
 $ doco build
+
 # or a different folder name
 $ doco --folder [folder] build
+
 # or a different output folder
 $ doco --output [output] build
 ```
@@ -17,4 +19,6 @@ When the docs folder does not exist, it stops the operation and error out with:
 
 ```sh
 ERROR: docs folder does not exist, aborting build
-```
+```
+
+The `--folder` parameter is optional and it will be used to set the name of the documentation folder. If the folder is not provided, it will default to `docs`. The `--output` parameter is optional and it will be used to set the name of the output folder. If the output folder is not provided, it will default to `public`.

docs/the_cli/help.md

@@ -0,0 +1,25 @@
+---
+title: Help
+index: 2
+---
+
+The help command prints usage information about the CLI.
+
+```sh
+$  doco help 
+Doco is a simple, lightweight, and easy to use documentation generator for Markdown files. It takes a directory of Markdown files and generates a static site with a table of contents.
+
+Usage
+    doco command [arguments]
+
+Commands
+    build     Generates the documentation site into the /public directory (see options)
+    help      Prints the CLI help
+    init      Creates a /docs directory with base files (see options)
+    serve     Starts a local server to view the documentation site
+
+Options:
+  --folder      source folder for the documentation
+  --output      folder to put the generated files
+```
+

docs/the_cli/serve.md

@@ -0,0 +1,13 @@
+---
+Title: Serve
+index: 2
+---
+
+Serve builds the static website and starts a local server to serve the static website on port 3000. It will also watch for changes in the markdown files and rebuild the website.
+
+```sh
+$ doco serve
+2024/01/19 13:46:16 > 👀 Watching for changes in docs
+2024/01/19 13:46:16 > Serving documentation on http://localhost:3000/
+2024/01/19 13:46:20 > docs/the_cli/build.md changed, documentation rebuilt.
+```

go.mod

@@ -3,9 +3,13 @@ module github.com/paganotoni/doco
 go 1.21
 
 require (
+	github.com/fsnotify/fsnotify v1.7.0
 	github.com/yuin/goldmark v1.5.4
 	github.com/yuin/goldmark-meta v1.1.0
 	golang.org/x/text v0.14.0
 )
 
-require gopkg.in/yaml.v2 v2.3.0 // indirect
+require (
+	golang.org/x/sys v0.5.0 // indirect
+	gopkg.in/yaml.v2 v2.3.0 // indirect
+)

go.sum

@@ -1,7 +1,11 @@
+github.com/fsnotify/fsnotify v1.7.0 h1:8JEhPFa5W2WU7YfeZzPNqzMP6Lwt7L2715Ggo0nosvA=
+github.com/fsnotify/fsnotify v1.7.0/go.mod h1:40Bi/Hjc2AVfZrqy+aj+yEI+/bRxZnMJyTJwOpGvigM=
 github.com/yuin/goldmark v1.5.4 h1:2uY/xC0roWy8IBEGLgB1ywIoEJFGmRrX21YQcvGZzjU=
 github.com/yuin/goldmark v1.5.4/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 github.com/yuin/goldmark-meta v1.1.0 h1:pWw+JLHGZe8Rk0EGsMVssiNb/AaPMHfSRszZeUeiOUc=
 github.com/yuin/goldmark-meta v1.1.0/go.mod h1:U4spWENafuA7Zyg+Lj5RqK/MF+ovMYtBvXi1lBb2VP0=
+golang.org/x/sys v0.5.0 h1:MUK/U/4lj1t1oPg0HfuXDN/Z1wv31ZJ/YcPiGccS4DU=
+golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=