feat: add no-styles flag for html docs

If `-no-styles` flag is enabled, HTML generated documentation will not include built-in CSS styles.
g4s8 · Dec 24, 2023 · 6dd1141 · 6dd1141
1 parent 49a3cac
commit 6dd1141
Show file tree

Hide file tree

Showing 13 changed files with 83 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -50,6 +50,7 @@ type Config struct {
  `plaintext` or `html`.
  * `-all` - Generate documentation for all types in the file.
  * `-env-prefix` - Environment variable prefix.
+ * `-no-styles` - Disable built-int CSS styles for HTML format.
 
 ## Example
 

diff --git a/_examples/complex-nostyle.html b/_examples/complex-nostyle.html
@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+    <meta charset="utf-8">
+    <title>Environment Variables</title>
+
+  </head>
+  <body>
+    <section>
+      <article>
+        <h1>Environment Variables</h1>
+
+  <h2>ComplexConfig</h2>
+<p>ComplexConfig is an example configuration structure.
+It contains a few fields with different types of tags.
+It is trying to cover all the possible cases.</p>
+  <ul>
+    <li><code>SECRET</code> (from-file) - Secret is a secret value that is read from a file.</li>
+    <li><code>PASSWORD</code> (from-file, default: <code>/tmp/password</code>) - Password is a password that is read from a file.</li>
+    <li><code>CERTIFICATE</code> (expand, from-file, default: <code>${CERTIFICATE_FILE}</code>) - Certificate is a certificate that is read from a file.</li>
+    <li><code>SECRET_KEY</code> (<strong>required</strong>) - Key is a secret key.</li>
+    <li><code>SECRET_VAL</code> (<strong>required</strong>, non-empty) - SecretVal is a secret value.</li>
+    <li><code>HOSTS</code> (separated by "<code>:</code>", <strong>required</strong>) - Hosts is a list of hosts.</li>
+    <li><code>WORDS</code> (comma-separated, from-file, default: <code>one,two,three</code>) - Words is just a list of words.</li>
+    <li><code>COMMENT</code> (<strong>required</strong>, default: <code>This is a comment.</code>) - Just a comment.</li>
+
+  </ul>
+
+  <h2>NextConfig</h2>
+
+  <ul>
+    <li><code>MOUNT</code> (<strong>required</strong>) - Mount is a mount point.</li>
+
+  </ul>
+
+      </article>
+    </section>
+  </body>
+</html>
diff --git a/_examples/complex.go b/_examples/complex.go
@@ -8,6 +8,7 @@ package main
 //go:generate go run ../ -output complex.md -all
 //go:generate go run ../ -output complex.txt -all -format plaintext
 //go:generate go run ../ -output x_complex.md -all -env-prefix X_
+//go:generate go run ../ -output complex-nostyle.html -format html -all -no-styles
 type ComplexConfig struct {
 	// Secret is a secret value that is read from a file.
 	Secret string `env:"SECRET,file"`

diff --git a/_examples/complex.html b/_examples/complex.html
@@ -3,7 +3,7 @@
     <head>
     <meta charset="utf-8">
     <title>Environment Variables</title>
-    <style>
+<style>
 * {
   box-sizing: border-box;
 }

diff --git a/_examples/config.html b/_examples/config.html
@@ -3,7 +3,7 @@
     <head>
     <meta charset="utf-8">
     <title>Environment Variables</title>
-    <style>
+<style>
 * {
   box-sizing: border-box;
 }

diff --git a/doc.go b/doc.go
@@ -36,5 +36,6 @@ Options:
     `plaintext` or `html`.
   - `-all` - Generate documentation for all types in the file.
   - `-env-prefix` - Environment variable prefix.
+  - `-no-styles` - Disable built-int CSS styles for HTML format.
 */
 package main
diff --git a/generator.go b/generator.go
@@ -12,6 +12,7 @@ type generator struct {
 	all        bool // generate documentation for all types in the file
 	tmpl       template
 	prefix     string
+	noStyles   bool
 }
 
 type generatorOption func(*generator) error
@@ -57,6 +58,13 @@ func withPrefix(prefix string) generatorOption {
 	}
 }
 
+func withNoStyles() generatorOption {
+	return func(g *generator) error {
+		g.noStyles = true
+		return nil
+	}
+}
+
 func newGenerator(fileName string, execLine int, opts ...generatorOption) (*generator, error) {
 	g := &generator{fileName: fileName, execLine: execLine}
 	for _, opt := range opts {
@@ -77,7 +85,7 @@ func (g *generator) generate(out io.Writer) error {
 		return fmt.Errorf("inspect file: %w", err)
 	}
 	renderer := templateRenderer(g.tmpl)
-	rctx := newRenderContext(data, g.prefix)
+	rctx := newRenderContext(data, g.prefix, g.noStyles)
 	if err := renderer(rctx, out); err != nil {
 		return err
 	}

diff --git a/generator_test.go b/generator_test.go
@@ -52,6 +52,15 @@ func TestOptions(t *testing.T) {
 			t.Fatal("expected prefix to be 'prefix'")
 		}
 	})
+	t.Run("WithNoStyles", func(t *testing.T) {
+		g, err := newGenerator("stub", 1, withNoStyles())
+		if err != nil {
+			t.Fatal("new generator error", err)
+		}
+		if g.noStyles != true {
+			t.Fatal("expected noStyles to be true")
+		}
+	})
 	t.Run("empty", func(t *testing.T) {
 		g, err := newGenerator("stub", 1)
 		if err != nil {

diff --git a/main.go b/main.go
@@ -15,6 +15,7 @@ type appConfig struct {
 	execLine       int
 	all            bool
 	envPrefix      string
+	noStyles       bool
 }
 
 func (cfg *appConfig) parseFlags(f *flag.FlagSet) error {
@@ -23,6 +24,7 @@ func (cfg *appConfig) parseFlags(f *flag.FlagSet) error {
 	f.StringVar(&cfg.formatName, "format", "", "Output format, default `markdown`")
 	f.BoolVar(&cfg.all, "all", false, "Generate documentation for all types in the file")
 	f.StringVar(&cfg.envPrefix, "env-prefix", "", "Environment variable prefix")
+	f.BoolVar(&cfg.noStyles, "no-styles", false, "Disable styles in html output")
 	if err := f.Parse(os.Args[1:]); err != nil {
 		return fmt.Errorf("parsing CLI args: %w", err)
 	}
@@ -99,6 +101,9 @@ func run(cfg *appConfig) (err error) {
 	if cfg.envPrefix != "" {
 		opts = append(opts, withPrefix(cfg.envPrefix))
 	}
+	if cfg.noStyles {
+		opts = append(opts, withNoStyles())
+	}
 	gen, err := newGenerator(cfg.inputFileName, cfg.execLine, opts...)
 	if err != nil {
 		return fmt.Errorf("creating generator: %w", err)

diff --git a/main_test.go b/main_test.go
@@ -13,6 +13,7 @@ func TestConfig(t *testing.T) {
 			"cmd",
 			"-output", "test.md",
 			"-type", "test",
+			"-no-styles",
 			"-format", "markdown",
 			"-env-prefix", "TEST_",
 			"-all",
@@ -39,6 +40,9 @@ func TestConfig(t *testing.T) {
 		if !cfg.all {
 			t.Fatal("Invalid all flag")
 		}
+		if !cfg.noStyles {
+			t.Fatal("Invalid no styles flag")
+		}
 
 		if err := cfg.parseEnv(); err != nil {
 			t.Fatal("Invalid environment:", err)

diff --git a/render.go b/render.go
@@ -30,11 +30,13 @@ type renderItem struct {
 type renderContext struct {
 	Title    string
 	Sections []renderSection
+	Styles   bool
 }
 
-func newRenderContext(scopes []*EnvScope, envPrefix string) renderContext {
+func newRenderContext(scopes []*EnvScope, envPrefix string, noStyles bool) renderContext {
 	res := renderContext{
 		Sections: make([]renderSection, len(scopes)),
+		Styles:   !noStyles,
 	}
 	res.Title = "Environment Variables"
 	for i, scope := range scopes {

diff --git a/render_test.go b/render_test.go
@@ -86,7 +86,7 @@ func TestRender(t *testing.T) {
 			`</html>`))
 	})
 	t.Run("sections", func(t *testing.T) {
-		rc := renderContext{Title: "Sections", Sections: testRenderSections}
+		rc := renderContext{Title: "Sections", Sections: testRenderSections, Styles: true}
 		t.Run("markdown", testRenderer(tmplMarkdown, rc,
 			"# Sections",
 			"## First",
@@ -107,6 +107,8 @@ func TestRender(t *testing.T) {
 			`<head>`,
 			`<meta charset="utf-8">`,
 			`<title>Sections</title>`,
+			`<style>`,
+			`</style>`,
 			`</head>`,
 			`<section>`,
 			`<article>`,
@@ -138,11 +140,14 @@ func TestNewRenderContext(t *testing.T) {
 			},
 		},
 	}
-	rc := newRenderContext(src, "PREFIX_")
+	rc := newRenderContext(src, "PREFIX_", false)
 	const title = "Environment Variables"
 	if rc.Title != title {
 		t.Errorf("expected title %q, got %q", title, rc.Title)
 	}
+	if rc.Styles != true {
+		t.Errorf("expected styles %v, got %v", true, rc.Styles)
+	}
 	if len(rc.Sections) != 1 {
 		t.Fatalf("expected 1 section, got %d", len(rc.Sections))
 	}

diff --git a/templ/html.tmpl b/templ/html.tmpl
@@ -3,6 +3,7 @@
     <head>
     <meta charset="utf-8">
     <title>{{ .Title }}</title>
+{{ if .Styles -}}
     <style>
 * {
   box-sizing: border-box;
@@ -70,6 +71,7 @@ p {
   margin-bottom: 16px;
 }
     </style>
+{{- end }}
   </head>
   <body>
     <section>
-Original file line number
+Diff line change
@@ Expand Up / @@ -3,7 +3,7 @@ @@
         <head>
         <meta charset="utf-8">
         <title>Environment Variables</title>
-        <style>
+    <style>
     * {
       box-sizing: border-box;
     }
@@ Expand Down @@