docs: getting started

jmattheis · Feb 19, 2024 · 9a74aca · 9a74aca
1 parent 15fc24c
commit 9a74aca
Show file tree

Hide file tree

Showing 4 changed files with 156 additions and 162 deletions.
diff --git a/README.md b/README.md
@@ -27,6 +27,7 @@ do is create an interface and execute goverter. The project is meant as
 alternative to [jinzhu/copier](https://github.com/jinzhu/copier) that doesn't
 use reflection.
 
+[Getting Started](https://goverter.jmattheis.de/guide/getting-started) ᛫
 [Installation](https://goverter.jmattheis.de/guide/install) ᛫
 [CLI](https://goverter.jmattheis.de/reference/cli) ᛫
 [Config](https://goverter.jmattheis.de/reference/settings)
@@ -47,87 +48,64 @@ use reflection.
 - Detailed [documentation](https://goverter.jmattheis.de/) with a lot examples
 - Thoroughly tested, see [our test scenarios](./scenario)
 
-## Getting Started
-
-1. Ensure your `go version` is 1.18 or above
-
-1. Create a go modules project if you haven't done so already
-
-    ```bash
-    $ go mod init module-name
-    ```
-
-1. Create your converter interface and mark it with a comment containing
-   [`goverter:converter`](https://goverter.jmattheis.de/reference/converter)
-
-    `input.go`
-
-    ```go
-    package example
-
-    // goverter:converter
-    type Converter interface {
-      ConvertItems(source []Input) []Output
-
-      // goverter:ignore Irrelevant
-      // goverter:map Nested.AgeInYears Age
-      Convert(source Input) Output
-    }
-
-    type Input struct {
-      Name string
-      Nested InputNested
-    }
-    type InputNested struct {
-      AgeInYears int
-    }
-    type Output struct {
-      Name string
-      Age int
-      Irrelevant bool
-    }
-    ```
-
-    See [Settings](https://goverter.jmattheis.de/reference/settings) for more information.
-
-1. Run `goverter`:
-
-    ```bash
-    $ go run github.com/jmattheis/goverter/cmd/goverter@latest gen ./
-    ```
-
-    It's recommended to use an explicit version instead of `latest`. See
-    [Installation](https://goverter.jmattheis.de/guide/install) and
-    [CLI](https://goverter.jmattheis.de/reference/cli) for more information.
-
-1. goverter created a file at `./generated/generated.go`, it may look like this:
-
-    ```go
-    package generated
-
-    import example "goverter/example"
-
-    type ConverterImpl struct{}
-
-    func (c *ConverterImpl) Convert(source example.Input) example.Output {
-        var exampleOutput example.Output
-        exampleOutput.Name = source.Name
-        exampleOutput.Age = source.Nested.AgeInYears
-        return exampleOutput
-    }
-    func (c *ConverterImpl) ConvertItems(source []example.Input) []example.Output {
-        var exampleOutputList []example.Output
-        if source != nil {
-            exampleOutputList = make([]example.Output, len(source))
-            for i := 0; i < len(source); i++ {
-                exampleOutputList[i] = c.Convert(source[i])
-            }
+## Example
+
+Given this converter:
+
+```go
+package example
+
+// goverter:converter
+type Converter interface {
+    ConvertItems(source []Input) []Output
+
+    // goverter:ignore Irrelevant
+    // goverter:map Nested.AgeInYears Age
+    Convert(source Input) Output
+}
+
+type Input struct {
+    Name string
+    Nested InputNested
+}
+type InputNested struct {
+    AgeInYears int
+}
+type Output struct {
+    Name string
+    Age int
+    Irrelevant bool
+}
+```
+
+Goverter will generated these conversion methods:
+
+```go
+package generated
+
+import example "goverter/example"
+
+type ConverterImpl struct{}
+
+func (c *ConverterImpl) Convert(source example.Input) example.Output {
+    var exampleOutput example.Output
+    exampleOutput.Name = source.Name
+    exampleOutput.Age = source.Nested.AgeInYears
+    return exampleOutput
+}
+func (c *ConverterImpl) ConvertItems(source []example.Input) []example.Output {
+    var exampleOutputList []example.Output
+    if source != nil {
+        exampleOutputList = make([]example.Output, len(source))
+        for i := 0; i < len(source); i++ {
+            exampleOutputList[i] = c.Convert(source[i])
         }
-        return exampleOutputList
     }
-    ```
+    return exampleOutputList
+}
+```
 
-    See [Generation](https://goverter.jmattheis.de/explanation/generation) for more information.
+See [Getting Started](https://goverter.jmattheis.de/guide/getting-started).
 
 ## Versioning
 

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -35,15 +35,16 @@ export default defineConfig({
       },
     },
     nav: [
-      { text: "Getting Started", link: "/" },
+      { text: "Getting Started", link: "/guide/getting-started" },
       { text: "Settings", link: "/reference/settings" },
-      { text: "FAQ", link: "/faq" },
+      { text: "Changelog", link: "/changelog" },
     ],
     sidebar: [
+      { text: "Intro", link: "/" },
       {
         text: "Guides",
         items: [
-          { text: "Getting Started", link: "/" },
+          { text: "Getting Started", link: "/guide/getting-started" },
           { text: "Installation", link: "/guide/install" },
           { text: "Error early", link: "/guide/error-early" },
           { text: "Convert Enums", link: "/guide/enum" },

diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
@@ -0,0 +1,78 @@
+# Getting started
+
+1. Ensure your `go version` is 1.18 or above
+
+1. Create a go modules project if you haven't done so already
+
+    ```bash
+    $ go mod init module-name
+    ```
+
+1. [Guide: Install Goverter](./install.md)
+
+1. Create your converter interface and mark it with a comment containing
+   [`goverter:converter`](https://goverter.jmattheis.de/reference/converter)
+
+    ::: code-group
+    ```go [input.go]
+    package example
+
+    // goverter:converter
+    type Converter interface {
+      ConvertItems(source []Input) []Output
+
+      // goverter:ignore Irrelevant
+      // goverter:map Nested.AgeInYears Age
+      Convert(source Input) Output
+    }
+
+    type Input struct {
+      Name string
+      Nested InputNested
+    }
+    type InputNested struct {
+      AgeInYears int
+    }
+    type Output struct {
+      Name string
+      Age int
+      Irrelevant bool
+    }
+    ```
+    :::
+
+1. Run Goverter. See [Guide: Install Goverter](./install.md)
+
+1. goverter created a file at `./generated/generated.go`, it may look like this:
+
+    ::: code-group
+    ```go [generated/generated.go]
+    package generated
+
+    import example "goverter/example"
+
+    type ConverterImpl struct{}
+
+    func (c *ConverterImpl) Convert(source example.Input) example.Output {
+        var exampleOutput example.Output
+        exampleOutput.Name = source.Name
+        exampleOutput.Age = source.Nested.AgeInYears
+        return exampleOutput
+    }
+    func (c *ConverterImpl) ConvertItems(source []example.Input) []example.Output {
+        var exampleOutputList []example.Output
+        if source != nil {
+            exampleOutputList = make([]example.Output, len(source))
+            for i := 0; i < len(source); i++ {
+                exampleOutputList[i] = c.Convert(source[i])
+            }
+        }
+        return exampleOutputList
+    }
+    ```
+    :::
+
+## What's next?
+
+You can look through the the [Structs Guide](./struct.md) and the [Settings
+Reference](../reference/settings.md) to find out what's possible with goverter.
diff --git a/docs/index.md b/docs/index.md
@@ -8,84 +8,21 @@ do is create an interface and execute goverter. The project is meant as
 alternative to [jinzhu/copier](https://github.com/jinzhu/copier) that doesn't
 use reflection.
 
-## Getting Started
-
-1. Ensure your `go version` is 1.18 or above
-
-1. Create a go modules project if you haven't done so already
-
-    ```bash
-    $ go mod init module-name
-    ```
-
-1. Create your converter interface and mark it with a comment containing
-   [`goverter:converter`](https://goverter.jmattheis.de/reference/converter)
-
-    `input.go`
-
-    ```go
-    package example
-
-    // goverter:converter
-    type Converter interface {
-      ConvertItems(source []Input) []Output
-
-      // goverter:ignore Irrelevant
-      // goverter:map Nested.AgeInYears Age
-      Convert(source Input) Output
-    }
-
-    type Input struct {
-      Name string
-      Nested InputNested
-    }
-    type InputNested struct {
-      AgeInYears int
-    }
-    type Output struct {
-      Name string
-      Age int
-      Irrelevant bool
-    }
-    ```
-
-    See [Settings](https://goverter.jmattheis.de/reference/settings) for more information.
-
-1. Run `goverter`:
-
-    ```bash-vue
-    $ go run github.com/jmattheis/goverter/cmd/goverter@{{ libVersion }} gen ./
-    ```
-
-    It's recommended to use an explicit version instead of `latest`. See
-    [Installation](https://goverter.jmattheis.de/guide/install) and
-    [CLI](https://goverter.jmattheis.de/reference/cli) for more information.
-
-1. goverter created a file at `./generated/generated.go`, it may look like this:
-
-    ```go
-    package generated
-
-    import example "goverter/example"
-
-    type ConverterImpl struct{}
-
-    func (c *ConverterImpl) Convert(source example.Input) example.Output {
-        var exampleOutput example.Output
-        exampleOutput.Name = source.Name
-        exampleOutput.Age = source.Nested.AgeInYears
-        return exampleOutput
-    }
-    func (c *ConverterImpl) ConvertItems(source []example.Input) []example.Output {
-        var exampleOutputList []example.Output
-        if source != nil {
-            exampleOutputList = make([]example.Output, len(source))
-            for i := 0; i < len(source); i++ {
-                exampleOutputList[i] = c.Convert(source[i])
-            }
-        }
-        return exampleOutputList
-    }
-    ```
-
-    See [Generation](https://goverter.jmattheis.de/explanation/generation) for more information.
+[Getting Started](./guide/getting-started) ᛫
+[Installation](./guide/install) ᛫
+[CLI](./reference/cli) ᛫
+[Config](./reference/settings)
+
+## Features
+
+- **Fast execution**: No reflection is used at runtime
+- Automatically converts builtin types: slices, maps, named types, primitive
+  types, pointers, structs with same fields
+- [Enum support](./guide/enum)
+- [Deep copies](https://en.wikipedia.org/wiki/Object_copying#Deep_copy) per
+  default and supports [shallow
+  copying](https://en.wikipedia.org/wiki/Object_copying#Shallow_copy)
+- **Customizable**: [You can implement custom converter methods](./reference/extend)
+- [Clear errors when generating the conversion methods](./guide/error-early) if
+  - the target struct has unmapped fields
+  - types cannot be converted without losing information