diff --git a/.vscode/schema.json b/.vscode/schema.json deleted file mode 100644 index e3e6735..0000000 --- a/.vscode/schema.json +++ /dev/null @@ -1,32 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Name of the project, normally this should match the repository name" - }, - "arguments": { - "type": "object", - "description": "Arguments to pass to stencil templates, consumable through stencil.Arg" - }, - "modules": { - "type": "array", - "description": "List of template repositories and native extensions to use when running stencil", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Import path of the module to use, e.g. github.com/username/repo" - }, - "version": { - "type": "string", - "description": "Version of the module to use, defaults to latest. Can either be a git tag or branch." - } - }, - "required": ["name"] - } - } - } -} diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index fc5aa8a..533fac9 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -21,6 +21,7 @@ export default defineConfig({ }, themeConfig: { // https://vitepress.dev/reference/default-theme-config + logo: 'logo.png', outline: 'deep', nav: [], sidebar: VitePressSidebar.generateSidebar(vitepressSidebarOptions), diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css new file mode 100644 index 0000000..1728b53 --- /dev/null +++ b/docs/.vitepress/theme/custom.css @@ -0,0 +1,7 @@ +:root { + --vp-c-brand-1: #d3183a; + --vp-c-brand-2: #c42b47; + --vp-c-brand-3: #bb4963; + --vp-home-hero-name-color: transparent; + --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #d11336 60%, #FFFFFF); +} diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js new file mode 100644 index 0000000..42fe9a9 --- /dev/null +++ b/docs/.vitepress/theme/index.js @@ -0,0 +1,4 @@ +import DefaultTheme from 'vitepress/theme' +import './custom.css' + +export default DefaultTheme diff --git a/docs/bun.lockb b/docs/bun.lockb index 896b03c..c44c746 100755 Binary files a/docs/bun.lockb and b/docs/bun.lockb differ diff --git a/docs/guide/base-project.md b/docs/guide/base-project.md index ee1771a..2d8e200 100644 --- a/docs/guide/base-project.md +++ b/docs/guide/base-project.md @@ -6,9 +6,13 @@ order: 2 This section will walk you through building a nearly-empty stenciled project and teach you how blocks work. While the sample project here is very Golang-centric, stencil can be used for any language! -> [!NOTE] -> This quick start uses `macOS` in the examples. For instructions about how to install Stencil on other operating systems, see [install](installation.md). -> It is required to have [Git installed](https://git-scm.com/downloads) to run this tutorial. +## Step 0: Prerequisites + +This tutorial requires the following things installed on your machine: + +- Git - Used by the `stencil` CLI, this is always required. +- [mise] - This is not required usually, but the module we'll look at does + require it. ## Step 1: Install Stencil @@ -16,13 +20,17 @@ If you don't already have stencil installed, follow the [documentation to instal ## Step 2: Create a `stencil.yaml` -First start by creating a new directory for your application, this should generally match whatever the name for your application is going to be. We'll go with `helloworld` here. +First start by creating a new directory for your application, this +should generally match whatever the name for your application is going +to be. We'll go with `helloworld` here. ```bash mkdir helloworld ``` -A [stencil.yaml](/reference/stencil.yaml) is integral to running stencil. It defines the modules you're consuming and the arguments to pass to them. +A [stencil.yaml](/reference/stencil.yaml) is integral to running +stencil. It defines the modules you're consuming and the arguments to +pass to them. Start with creating a basic `stencil.yaml`: @@ -36,152 +44,194 @@ arguments: {} modules: [] ``` -Now run `stencil`, you should have... nothing! That's expected because we didn't define any modules yet. +Now run `stencil`, you should have... nothing! That's expected because +we didn't define any modules yet. ```bash helloworld ❯ stencil -INFO[0000] stencil v1.14.2 -INFO[0002] Fetching dependencies -INFO[0002] Loading native extensions -INFO[0002] Rendering templates -INFO[0002] Writing template(s) to disk -INFO[0002] Running post-run command(s) +INFO stencil 0.9.0 +INFO Fetching dependencies +INFO Loading native extensions +INFO Rendering templates +INFO Writing template(s) to disk +INFO Running post-run command(s) helloworld ❯ ls -alh -drwxr-xr-x 4 jaredallard wheel 128B May 4 20:16 . -drwxr-xr-x 9 jaredallard wheel 288B May 4 20:16 .. --rw-r--r-- 1 jaredallard wheel 213B May 4 20:16 stencil.yaml --rw-r--r-- 1 jaredallard wheel 78B May 4 20:16 stencil.lock +drwxr-xr-x 2 jaredallard jaredallard 4.0K Aug 29 19:51 . +drwxr-xr-x 8 jaredallard jaredallard 4.0K Aug 29 19:49 .. +-rw-r--r-- 1 jaredallard jaredallard 37 Aug 29 19:51 stencil.lock +-rw-r--r-- 1 jaredallard jaredallard 43 Aug 29 19:50 stencil.yaml ``` > [!NOTE] > You'll notice there's a `stencil.lock` file here. > > ```yaml -> version: 0.8.0 +> version: 0.9.0 > modules: [] > files: [] > ``` > -> This will keep track of what files were created by stencil and what created them, as well as the last ran version of your modules. This file is very important! +> This will keep track of what files were created by stencil and what +> created them, as well as the last ran version of your modules. This +> file is very important! ## Step 3: Import a Module -Now that we've created our first stencil application, you're going to want to import a module! Let's import the [`stencil-base`](https://github.com/getoutreach/stencil-base) module. stencil-base includes a bunch of scripts and other building blocks for a Golang project. Let's take a look at it's `manifest.yaml` to see what arguments are required. +Now that we've created our first stencil application, you're going to +want to import a module! Let's import the +[`stencil-golang`](https://github.com/rgst-io/stencil-golang) module. +This module is for creating a Go service or CLI, but don't worry, you +don't need to know Go for this example! + +First, let's take a look at parameters exposed through `stencil-golang`. +This can be done by looking at the `manifest.yaml` provided by it. + +> [!NOTE] The full manifest can be found +> [here](https://github.com/rgst-io/stencil-golang/blob/e2ea9a1980f765f668d4a42d1f9108db777bf86d/manifest.yaml) ```yaml -name: github.com/getoutreach/stencil-base +name: github.com/rgst-io/stencil-golang --- arguments: - description: + org: + description: The Github organization to use for the project required: true - type: string - description: The purpose of this repository + + library: + copyrightHolder: + license: + commands: ``` -We can see that `description` is a required argument, so let's add it! Modify the `stencil.yaml` to set `arguments.description` to `"My awesome service!"` +We can see that the `org` argument is required and that it should be the +Github organization that our repository will live under. For now, since +we're not pushing this anywhere, it can be anything. So, let's go with +`rgst-io`. ```yaml name: helloworld -arguments: {} -description: "My awesome service!" +arguments: + org: rgst-io modules: - - name: github.com/getoutreach/stencil-base + - name: github.com/rgst-io/stencil-golang ``` Now if we run stencil we'll see that we have some files! ```bash helloworld ❯ stencil -INFO[0000] stencil v1.14.2 -INFO[0000] Fetching dependencies -INFO[0001] -> github.com/getoutreach/stencil-base v0.2.0 -INFO[0001] Loading native extensions -INFO[0001] Rendering templates -INFO[0001] Writing template(s) to disk -INFO[0001] -> Created .editorconfig -INFO[0001] -> Created .github/CODEOWNERS -INFO[0001] -> Created .github/pull_request_template.md -INFO[0001] -> Created .gitignore -INFO[0001] -> Created .releaserc.yaml -INFO[0001] -> Created CONTRIBUTING.md -INFO[0001] -> Skipped LICENSE -INFO[0001] -> Created README.md -INFO[0001] -> Skipped helpers -INFO[0001] -> Created package.json -INFO[0001] -> Created scripts/devbase.sh -INFO[0001] -> Created scripts/shell-wrapper.sh -INFO[0001] Running post-run command(s) +INFO stencil 0.9.0 +INFO Fetching dependencies +INFO -> github.com/rgst-io/stencil-golang v1.0.0 (b81af6111ff23879d56faa735c428dc2e8ff45b5) +INFO Loading native extensions +INFO Rendering templates +INFO Writing template(s) to disk +INFO -> Created LICENSE +INFO -> Created .goreleaser.yaml +INFO -> Created cmd/helloworld/helloworld.go +INFO -> Created CONTRIBUTING.md +INFO -> Created .github/workflows/release.yaml +INFO -> Created .github/workflows/tests.yaml +INFO -> Created .vscode/settings.json +INFO -> Created .mise.toml +INFO -> Created .github/scripts/get-next-version.sh +INFO -> Created .github/settings.yml +INFO -> Created .cliff.toml +INFO -> Created .mise/tasks/changelog-release +INFO -> Created package.json +INFO -> Created .vscode/extensions.json +INFO -> Created go.mod +INFO -> Created .editorconfig +INFO -> Created .gitignore +INFO -> Created .vscode/common.code-snippets +INFO Running post-run command(s) ... -helloworld ❯ ls -alh -drwxr-xr-x 4 jaredallard wheel 128B May 4 20:16 . -drwxr-xr-x 9 jaredallard wheel 288B May 4 20:16 .. --rw-r--r-- 1 jaredallard wheel 274B May 4 20:26 .editorconfig -drwxr-xr-x 4 jaredallard wheel 128B May 4 20:26 .github --rw-r--r-- 1 jaredallard wheel 795B May 4 20:26 .gitignore --rw-r--r-- 1 jaredallard wheel 857B May 4 20:26 .releaserc.yaml --rw-r--r-- 1 jaredallard wheel 417B May 4 20:26 CONTRIBUTING.md --rw-r--r-- 1 jaredallard wheel 703B May 4 20:26 README.md --rw-r--r-- 1 jaredallard wheel 474B May 4 20:26 package.json -drwxr-xr-x 4 jaredallard wheel 128B May 4 20:26 scripts --rw-r--r-- 1 jaredallard wheel 2.1K May 4 20:26 stencil.lock --rw-r--r-- 1 jaredallard wheel 118B May 4 20:26 stencil.yaml -``` - -## Step 4: Modifying a Block - -One of the key features in stencil is the notion of "blocks". Modules expose a block where they want developers to modify the code. Let's look at the `stencil-base` module to see what blocks are available. - -In `README.md` we can see a basic block called "overview": - -```md -# helloworld - -... +# Note: If you see an error about bun/prettier, simply run +# 'bun install' and re-run stencil. Sorry about that! -## High-level Overview - - - - +helloworld ❯ ls -alh +drwxr-xr-x 6 jaredallard jaredallard 4.0K Aug 29 19:58 . +drwxr-xr-x 8 jaredallard jaredallard 4.0K Aug 29 19:49 .. +-rw-r--r-- 1 jaredallard jaredallard 4.3K Aug 29 19:58 .cliff.toml +-rw-r--r-- 1 jaredallard jaredallard 185 Aug 29 19:58 .editorconfig +drwxr-xr-x 4 jaredallard jaredallard 4.0K Aug 29 19:58 .github +-rw-r--r-- 1 jaredallard jaredallard 583 Aug 29 19:58 .gitignore +-rw-r--r-- 1 jaredallard jaredallard 1.1K Aug 29 19:58 .goreleaser.yaml +drwxr-xr-x 3 jaredallard jaredallard 4.0K Aug 29 19:58 .mise +-rw-r--r-- 1 jaredallard jaredallard 1.3K Aug 29 19:58 .mise.toml +drwxr-xr-x 2 jaredallard jaredallard 4.0K Aug 29 19:58 .vscode +-rw-r--r-- 1 jaredallard jaredallard 217 Aug 29 19:58 CONTRIBUTING.md +-rw-r--r-- 1 jaredallard jaredallard 35K Aug 29 19:58 LICENSE +drwxr-xr-x 3 jaredallard jaredallard 4.0K Aug 29 19:58 cmd +-rw-r--r-- 1 jaredallard jaredallard 46 Aug 29 19:58 go.mod +-rw-r--r-- 1 jaredallard jaredallard 130 Aug 29 19:58 package.json +-rw-r--r-- 1 jaredallard jaredallard 2.4K Aug 29 19:58 stencil.lock +-rw-r--r-- 1 jaredallard jaredallard 96 Aug 29 19:58 stencil.yaml ``` -Let’s add some content in two places. One inside the block, one outside: - -```md -... - -## High-level Overview +Great, now we have all of these files! What stencil did was completely +generate this application for us as well as integrate with [mise] to set +up our toolchain. -hello, world! +## Step 4: Modifying a Block - +One of the key features in stencil is the notion of "blocks". Modules +expose a block where they want developers to modify the code. Let's look +at the `stencil-golang` module to see what blocks are available. -hello, world! +Let's look at `.goreleaser.yaml`. This is a system for creating and +releasing Go binaries. Opening the file, we can see something like this: - +```yaml +--- +builds: + - main: ./cmd/helloworld + flags: + - -trimpath + ldflags: + - -s + - -w + ## <> + + ## <> ``` -If we re-run stencil, notice how the contents of `README.md` have changed: - -```md -... - -## High-level Overview +A normal customization that Go application do is add `ldflags`, which +are linker-time modifications to variables. This is normally done with +something like a version string. - +Here, we could add our own version string injection inside of the block. -hello, world! - - +```yaml +--- +builds: + - main: ./cmd/helloworld + flags: + - -trimpath + ldflags: + - -s + - -w + ## <> + - -X main.Version="myVersion" + ## <> ``` -The contents of `README.md` have changed, but the contents within the block have not. This is the power of blocks, modules are able to change the content _around_ a user's content without affecting the user's content. This can be taken even further if a template decides to parse the code within a block at runtime, for example using the ast package to rewrite go code. +Now, if you re-run `stencil`, you'll see that it updated the file, but +did not change the contents. This is the "block" functionality that +makes up the core of `stencil`. This allows you to generate your files, +but most importantly _keep them updated_. ## Reflection -In all, we've created a `stencil.yaml`, added a module to it, ran stencil, and then modified the contents within a block. That's it! We've imported a base module and created some files, all without doing much of anything on our side. Hopefully that shows you the power of stencil. +In all, we've created a `stencil.yaml`, added a module to it, ran +stencil, and then modified the contents within a block. That's it! We've +imported a base module and created some files, all without doing much of +anything on our side. Hopefully that shows you the power of stencil. + +For more resources be sure to dive into [how to create a module](basic-module.md) +to get insight on how to create a module. -For more resources be sure to dive into [how to create a module](basic-module.md) to get insight on how to create a module. +[mise]: https://mise.jdx.dev diff --git a/docs/guide/basic-module.md b/docs/guide/basic-module.md index 348a378..dd4d718 100644 --- a/docs/guide/basic-module.md +++ b/docs/guide/basic-module.md @@ -5,95 +5,73 @@ order: 3 # Basic Stencil Module > [!NOTE] -> This quick start assumes you're familiar with stencil usage already. If you aren't be sure to go through the [reference documentation](/reference/) or the [quick start](/guide/). +> This quick start assumes you're familiar with stencil usage already. +> If you aren't be sure to go through the [reference +> documentation](/reference/) or the [quick start](/guide/). ## Step 1: Create a module -Using the `stencil create` command we're able to quickly create a module, let's start with a simple hello world module. +Using the `stencil create` command we're able to quickly create a +module, let's start with a simple hello world module. ```bash mkdir helloworld; cd helloworld stencil create module github.com/yourorg/helloworld ``` -You'll notice that when running that command, stencil itself was ran. This is because `stencil create` uses the [`stencil-template-base`](https://github.com/getoutreach/stencil-template-base), the [`stencil-base`](https://github.com/getoutreach/stencil-base), and the [`stencil-circleci`](https://github.com/getoutreach/stencil-circleci) modules by default. This brings automatic CI and testing support to your module. +You'll notice this created a `stencil.yaml` file and ran `stencil` on +itself. This isn't used now, but will be in the future. -Let's briefly look at what it's created: - -```bash -helloworld ❯ ls -alh -total 616 -drwxr-xr-x 23 jaredallard wheel 736B May 4 20:41 . -drwxr-xr-x 9 jaredallard wheel 288B May 4 20:40 .. -drwxr-xr-x 32 jaredallard wheel 1.0K May 4 20:41 .bootstrap -drwxr-xr-x 3 jaredallard wheel 96B May 4 20:41 .circleci --rw-r--r-- 1 jaredallard wheel 274B May 4 20:41 .editorconfig -drwxr-xr-x 4 jaredallard wheel 128B May 4 20:41 .github --rw-r--r-- 1 jaredallard wheel 795B May 4 20:41 .gitignore --rw-r--r-- 1 jaredallard wheel 896B May 4 20:41 .releaserc.yaml --rw-r--r-- 1 jaredallard wheel 417B May 4 20:41 CONTRIBUTING.md --rw-r--r-- 1 jaredallard wheel 11K May 4 20:41 LICENSE.txt --rw-r--r-- 1 jaredallard wheel 160B May 4 20:41 Makefile --rw-r--r-- 1 jaredallard wheel 684B May 4 20:41 README.md --rw-r--r-- 1 jaredallard wheel 118B May 4 20:41 bootstrap.lock --rw-r--r-- 1 jaredallard wheel 5.5K May 4 20:41 go.mod --rw-r--r-- 1 jaredallard wheel 101K May 4 20:41 go.sum --rw-r--r-- 1 jaredallard wheel 74B May 4 20:41 manifest.yaml -drwxr-xr-x 375 jaredallard wheel 12K May 4 20:41 node_modules --rw-r--r-- 1 jaredallard wheel 474B May 4 20:41 package.json -drwxr-xr-x 5 jaredallard wheel 160B May 4 20:41 scripts --rw-r--r-- 1 jaredallard wheel 3.4K May 4 20:41 stencil.lock --rw-r--r-- 1 jaredallard wheel 138B May 4 20:41 stencil.yaml -drwxr-xr-x 3 jaredallard wheel 96B May 4 20:41 templates --rw-r--r-- 1 jaredallard wheel 140K May 4 20:41 yarn.lock -``` - -A lot of files were created, the majority of these are niceties, like an automatic LICENSE (Apache-2.0), a README, and a CONTRIBUTING.md. Then there's also automatic .gitignore, circleci configuration for CI and a .releaserc for conventional commit powered releases. For more information for how to use these files, see the [template-base documentation](https://github.com/getoutreach/stencil-template-base). - -The most important directory is the `templates/` directory, which will contain any templates we want to render. +Not created for you is the `templates/` directory. This is where your +templates will live. ## Step 2: Creating a Template -Let's create a template that creates a simple hello world message in Go. We'll start by creating a `hello.go.tpl` in the `templates/` directory. +Let's create a template that creates a simple hello world message in Go. +We'll start by creating a `hello.go.tpl` in the `templates/` directory. ```go package main func main() { - fmt.Println("Hello, world!") + fmt.Println("Hello, world!") } ``` ## Step 3: Consuming the Module in an Application -Now that we've done that, how do we test it locally without CI'ing up a full build? This is super easy with the `replacements` map in a [`stencil.yaml`](/reference/stencil.yaml). +Now that we've done that, how do we test it locally without CI'ing up a +full build? This is super easy with the `replacements` map in a +[`stencil.yaml`](/reference/stencil.yaml). Let's quickly create a test application: ```bash mkdir testapp; cd testapp -cat > stencil.yaml <stencil.yaml < github.com/yourorg/helloworld local -INFO[0002] Loading native extensions -INFO[0002] Rendering templates -INFO[0002] Writing template(s) to disk -INFO[0002] -> Created hello.go +INFO stencil 0.9.0 +INFO Fetching dependencies +INFO -> github.com/yourorg/helloworld local +INFO Loading native extensions +INFO Rendering templates +INFO Writing template(s) to disk +INFO -> Created hello.go +INFO Running post-run command(s) ``` It looks like it created `hello.go` for us! Let's validate: @@ -103,7 +81,7 @@ testapp ❯ cat hello.go package main func main() { - fmt.Println("Hello, world!") + fmt.Println("Hello, world!") } ``` @@ -114,7 +92,8 @@ func main() { Blocks are incredibly easy to use in Stencil. > [!NOTE] -> In case you don't remember, blocks are areas in your generated code that you'd like to persist across runs. +> In case you don't remember, blocks are areas in your generated code +> that you'd like to persist across runs. Let's create our own block in the hello.go template from earlier: @@ -122,12 +101,12 @@ Let's create our own block in the hello.go template from earlier: package main func main() { - fmt.Println("Hello, world!") + fmt.Println("Hello, world!") - // <> - {{- /* It's important to not indent the file.Block to prevent the indentation from being copied over and.. over again. */ }} + // <> + {{- /* It's important to not indent the file.Block to prevent the indentation from being copied over and.. over again. */ }} {{ file.Block "additionalMessage" }} - // <> + // <> } ``` @@ -137,29 +116,34 @@ If we re-run stencil and look at `hello.go` we should see the following: package main func main() { - fmt.Println("Hello, world!") - // <> + fmt.Println("Hello, world!") + // <> - // <> + // <> } ``` -If we add contents to the block and re-run stencil they'll be persisted across the run! +If we add contents to the block and re-run stencil they'll be persisted +across the run! ## Step 5: (Optional/Advanced) Creating Multiple Files -One of the powerful parts of stencil is the ability to create an arbitrary number of files with a single template. This is done with the [`file.Create`](/functions/file.Create) function. Let's create a `greeter.go.tpl` template in the `templates/` directory that'll create `.go` based on the `greetings` argument. - -```tpl -# This is important! We don't want to create a greeter.go file +One of the powerful parts of stencil is the ability to create an +arbitrary number of files with a single template. This is done with the +[`file.Create`](/functions/file.Create) function. Let's create a +`greeter.go.tpl` template in the `templates/` directory that'll create +`.go` based on the `greetings` argument. +```go +# This is important! We do not want to create a greeter.go file {{- $_ := file.Skip "Generates multiple files" }} + {{- define "greeter" -}} {{- $greeting := .greeting }} package main func main() { -fmt.Println("$greeting, world!") + fmt.Println("$greeting, world!") } {{- end -}} @@ -179,7 +163,10 @@ fmt.Println("$greeting, world!") ``` > [!NOTE] -> Blocks are supported in multiple files! When `file.SetPath` is called the host is searched to see if a file already exists at that path, if it does it is searched to see if it contains any blocks, if it does they are loaded and accessible via `file.Block` as normal +> Blocks are supported in multiple files! When `file.SetPath` is called +> the host is searched to see if a file already exists at that path, if +> it does it is searched to see if it contains any blocks, if it does +> they are loaded and accessible via `file.Block` as normal Now let's modify the `manifest.yaml` to accept the argument `greetings`: @@ -187,9 +174,10 @@ Now let's modify the `manifest.yaml` to accept the argument `greetings`: arguments: greetings: description: A list of greetings to use -type: list -require: true -default: ["hello", "goodbye"] + required: true + default: ["hello", "goodbye"] + schema: + type: arrary ``` If we now run stencil on the test application, we should see the following: @@ -206,7 +194,9 @@ INFO[0002] -> Created hello.go INFO[0002] -> Created goodbye.go ``` -> [!NOTE] > `hello` and `goodbye` came from the default list of greetings that was set in the `manifest.yaml` file. Setting `arguments.greetings` on the test application and see it change! +> [!NOTE] > `hello` and `goodbye` came from the default list of +> greetings that was set in the `manifest.yaml` file. Setting +> `arguments.greetings` on the test application and see it change! If we look at the files, we should see the following: @@ -215,17 +205,23 @@ testapp ❯ cat hello.go package main func main() { - fmt.Println("hello, world!") + fmt.Println("hello, world!") } testapp ❯ cat goodbye.go package main func main() { - fmt.Println("goodbye, world!") + fmt.Println("goodbye, world!") } ``` ## Reflection -We've created a module, used it in a test application via the `replacements` map in the `stencil.yaml` and used a block. Optionally we've also created multiple files with a template. This is just the beginning of what you can do with modules. Modules have a rich amount of [functions](/functions/) available to them. Check out the [reference](/reference/) for more information about modules and how to use them. +We've created a module, used it in a test application via the +`replacements` map in the `stencil.yaml` and used a block. Optionally +we've also created multiple files with a template. This is just the +beginning of what you can do with modules. Modules have a rich amount of +[functions](/functions/) available to them. Check out the +[reference](/reference/) for more information about modules and how to +use them. diff --git a/docs/guide/basic-native-extension.md b/docs/guide/basic-native-extension.md index 3c2b261..5f3cd0a 100644 --- a/docs/guide/basic-native-extension.md +++ b/docs/guide/basic-native-extension.md @@ -9,21 +9,26 @@ order: 4 > usage already. If you aren't, be sure to go through the > [reference documentation](/reference/) or the other quick starts > here before proceeding. You've been warned! +> +> Also, if you get stuck, take a look at [stencil-golang's native +> extension](https://github.com/rgst-io/stencil-golang/blob/main/internal/plugin/plugin.go). +> It's a great example which only fetches license information from the +> Github API! -# What is a Native Extension? +## What is a Native Extension? Native extensions are special module types that don't use go-templates to integrate with stencil. Instead they expose template functions written in another language that can be called by stencil templates. -# How to create a Native Extension +## How to create a Native Extension This quick start will focus on creating a Go native extension. While other languages may work as well, there currently is no official documentation or support for those languages (if you're interested in another language please contribute it back!). -## Step 1: Create a Native Extension +### Step 1: Create a Native Extension Much like a module we're going to use the [`stencil create module`] command to create a native extension. @@ -37,7 +42,7 @@ However, instead of using the `templates/` directory we're going to create a `plugin/` directory. ```bash -rm templates; mkdir plugin +rm -f templates; mkdir plugin ``` Now that we've created the `plugin/` directory we're going to created a @@ -94,7 +99,7 @@ func main() { Next, we'll need to build the plugin: `go build -o bin/plugin .` -## Step 2: Using in a Test Module +### Step 2: Using in a Test Module Let's create a `testmodule` to consume the native extension. @@ -117,7 +122,7 @@ modules: - name: github.com/yourorg/helloworld ``` -## Step 3: Running the Test Module +### Step 3: Running the Test Module Now, in order to test the native extension and the module consuming it we'll need to create a test application. @@ -139,7 +144,7 @@ Now, if we run `stencil` we should get a `hello.txt` file in our test applicatio ```bash testapp ❯ stencil -INFO stencil v0.8.0 +INFO stencil v0.9.0 INFO Fetching dependencies INFO -> github.com/yourorg/helloworld local INFO Loading native extensions @@ -153,7 +158,7 @@ helloWorld Success! :tada: -# Reflection +## Reflection To reflect, we've created a `hello.txt.tpl` file that calls the `helloWorld` function in the native extension we implemented. diff --git a/docs/guide/installation.md b/docs/guide/installation.md index a5025d0..a436828 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -55,6 +55,20 @@ echo "https://alpine.fury.io/rgst-io/" >> /etc/apk/repositories curl https://alpine.fury.io/rgst-io/rgst-io@fury.io-946e9786.rsa.pub | sudo tee /etc/apk/keys/'rgst-io@fury.io-946e9786.rsa.pub' >/dev/null ``` +### Github Action + +Quickstart: + +```yaml +- name: Install Stencil + uses: rgst-io/stencil-action@latest + with: + github-token: ${{ github.token }} + version: "latest" +``` + +[Github Action Documentation](https://github.com/marketplace/actions/stencil-action) + ### Binary (Cross-platform) Download the appropriate version for your platform from [Stencil Releases](https://github.com/rgst-io/stencil/releases). Once downloaded, the binary can be run from anywhere. You don't need to install it into a global location. This works well for shared hosts and other systems where you don't have a privileged account. diff --git a/docs/index.md b/docs/index.md index 74a2c1b..09cc26f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,6 +7,9 @@ hero: name: stencil tagline: | A modern living-template engine for evolving repositories + image: + src: /logo.png + alt: stencil actions: - theme: brand text: About @@ -19,8 +22,13 @@ hero: link: https://github.com/rgst-io/stencil features: - - title: Development Lifecycle Management - details: stencil goes further than other templating tools by defining extensibility "blocks" to explicitly separate what your consumers can and can't extend, encouraging a system of regularly re-running stencil to pull in living-and-progressing templates. - - title: Native Extensions - details: Need to interface with an API or implement custom parsing/merging logic? Stencil supports native extensions in _any_ language to implement that logic. + - icon: 📝 + title: Development Lifecycle Management + details: Treat your generated files as APIs by persisting changes in customizable "blocks" to allow rendering more than once + - icon: 🧱 + title: Modular + details: Templates can be composed through importable modules allowing easy customization + - icon: 🛠️ + title: Native Extensions + details: Need to interface with an API or implement custom parsing/merging logic? Stencil supports native extensions in any language to implement that logic --- diff --git a/docs/logo.png b/docs/logo.png new file mode 100644 index 0000000..e1c205a Binary files /dev/null and b/docs/logo.png differ diff --git a/docs/package.json b/docs/package.json index 57fbd20..930cbbb 100644 --- a/docs/package.json +++ b/docs/package.json @@ -3,12 +3,12 @@ "private": true, "type": "module", "devDependencies": { - "vitepress": "^1.2.3", - "vitepress-sidebar": "^1.23.2" + "vitepress": "^1.3.4", + "vitepress-sidebar": "^1.25.0" }, "scripts": { "docs:dev": "vitepress dev", - "docs:build": "vitepress build", + "docs:build": "vitepress build && cp logo.png .vitepress/dist && mkdir -p .vitepress/dist/static && cp ../schemas/* .vitepress/dist/static", "docs:preview": "vitepress preview" } } diff --git a/go.work.sum b/go.work.sum index 1a9ca22..4f9d187 100644 --- a/go.work.sum +++ b/go.work.sum @@ -1475,6 +1475,7 @@ github.com/cpuguy83/go-md2man/v2 v2.0.0/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsr github.com/cpuguy83/go-md2man/v2 v2.0.1/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= github.com/creack/pty v1.1.7/go.mod h1:lj5s0c3V2DBrqTV7llrYr5NG6My20zk30Fl46Y7DoTY= +github.com/creack/pty v1.1.9 h1:uDmaGzcdjhF4i/plgjmEsriH11Y0o7RKapEf/LDaM3w= github.com/creack/pty v1.1.21 h1:1/QdRyBaHHJP61QkWMXlOIBfsgdDeeKfK8SYVUWJKf0= github.com/creack/pty v1.1.21/go.mod h1:MOBLtS5ELjhRRrroQr9kyvTxUAFNvYEK993ew/Vr4O4= github.com/cyphar/filepath-securejoin v0.2.4/go.mod h1:aPGpWjXOXUn2NCNjFvBE6aRxGGx79pTxQpKOJNYHHl4= @@ -1807,6 +1808,7 @@ github.com/ianlancetaylor/demangle v0.0.0-20200824232613-28f6c0f3b639/go.mod h1: github.com/ianlancetaylor/demangle v0.0.0-20220319035150-800ac71e25c2/go.mod h1:aYm2/VgdVmcIU8iMfdMvDMsRAQjcfZSKFby6HOFvi/w= github.com/icza/mighty v0.0.0-20210726202234-1719e2dcca1b/go.mod h1:klfNufgs1IcVNz2fWjXufNHkhl2cqIUbFoia2580Iv4= github.com/icza/session v1.2.0/go.mod h1:YR0WpaAv86zKUYA/9ftt0jgzHB/faiGRPx7Dk9omoew= +github.com/imdario/mergo v0.3.12 h1:b6R2BslTbIEToALKP7LxUvijTsNI9TAe80pLWN2g/HU= github.com/imdario/mergo v0.3.12/go.mod h1:jmQim1M+e3UYxmgPu/WyfjB3N3VflVyUjjjwH0dnCYA= github.com/imdario/mergo v0.3.13/go.mod h1:4lJ1jqUDcsbIECGy0RUJAXNIhg+6ocWgb1ALK2O4oXg= github.com/inconshreveable/mousetrap v1.0.0 h1:Z8tu5sraLXCXIcARxBp/8cbvlwVa7Z1NHg9XEKhtSvM= @@ -2217,6 +2219,7 @@ github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9de github.com/yuin/goldmark v1.1.32/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74= github.com/yuin/goldmark v1.3.5/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k= github.com/yuin/goldmark v1.4.1/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k= +github.com/yuin/goldmark v1.4.13 h1:fVcFKWvrslecOb/tg+Cc05dkeYx540o0FuFt3nUVDoE= github.com/yuin/goldmark v1.5.2/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY= github.com/yuin/goldmark v1.5.4 h1:2uY/xC0roWy8IBEGLgB1ywIoEJFGmRrX21YQcvGZzjU= github.com/yuin/goldmark v1.5.4/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY= @@ -2545,6 +2548,8 @@ golang.org/x/sync v0.5.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= golang.org/x/sync v0.7.0 h1:YsImfSBoP9QPYL0xyKJPq0gcaJdG3rInoqxTWbfQu9M= golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= +golang.org/x/sync v0.8.0 h1:3NFvSEYkUoMifnESzZl15y791HH1qU2xm6eCJU5ZPXQ= +golang.org/x/sync v0.8.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= golang.org/x/sys v0.0.0-20180823144017-11551d06cbcc/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/sys v0.0.0-20180905080454-ebe1bf3edb33/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= @@ -2762,6 +2767,7 @@ golang.org/x/tools v0.14.0/go.mod h1:uYBEerGOWcJyEORxN+Ek8+TT266gXkNlHdJBwexUsBg golang.org/x/tools v0.16.0/go.mod h1:kYVVN6I1mBNoB1OX+noeBjbRk4IUEPa7JJ+TJMEooJ0= golang.org/x/tools v0.21.0 h1:qc0xYgIbsSDt9EyWz05J5wfa7LOVW0YTLOXrqdLAWIw= golang.org/x/tools v0.21.0/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk= +golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d h1:vU5i/LfpvrRCpgM/VPfJLg5KjxD3E+hfT1SH+d9zLwg= golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk= golang.org/x/tools v0.23.0/go.mod h1:pnu6ufv6vQkll6szChhK3C3L/ruaIv5eBeztNG8wtsI= golang.org/x/xerrors v0.0.0-20190410155217-1f06c39b4373/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= @@ -3180,6 +3186,7 @@ gopkg.in/fatih/color.v1 v1.7.0 h1:bYGjb+HezBM6j/QmgBfgm1adxHpzzrss6bj4r9ROppk= gopkg.in/fsnotify.v1 v1.4.7 h1:xOHLXZwVvI9hhs+cLKq5+I5onOuwQLhQwiu63xxlHs4= gopkg.in/inconshreveable/log15.v2 v2.0.0-20180818164646-67afb5ed74ec/go.mod h1:aPpfJ7XW+gOuirDoZ8gHhLh3kZ1B08FtV2bbmy7Jv3s= gopkg.in/ini.v1 v1.51.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k= +gopkg.in/ini.v1 v1.62.0 h1:duBzk771uxoUuOlyRLkHsygud9+5lrlGjdFBb4mSKDU= gopkg.in/ini.v1 v1.62.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k= gopkg.in/ini.v1 v1.67.0 h1:Dgnx+6+nfE+IfzjUEISNeydPJh9AXNNsWbGP9KzCsOA= gopkg.in/ini.v1 v1.67.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=