From b1937b911bae2a63250d6772a794217da8ee2358 Mon Sep 17 00:00:00 2001 From: Sergey Polzunov Date: Mon, 1 Apr 2024 18:07:11 +0200 Subject: [PATCH] Documentation improvements (#143) --- .gitignore | 6 +++--- docs/_index.md | 9 ++++++--- docs/cli.md | 3 ++- docs/content-providers.md | 3 ++- docs/data-sources.md | 3 ++- docs/install.md | 7 ++++--- docs/language/_index.md | 1 + docs/language/configs.md | 1 + docs/language/content-blocks.md | 3 ++- docs/language/data-blocks.md | 1 + docs/language/documents.md | 1 + docs/language/references.md | 6 ++++-- docs/language/section-blocks.md | 1 + docs/language/syntax.md | 17 +++++++++++------ docs/plugins/_index.md | 19 +++++++++++++------ docs/tutorial.md | 24 ++++++++++++------------ 16 files changed, 66 insertions(+), 39 deletions(-) diff --git a/.gitignore b/.gitignore index a0df6f17..6e3f292c 100644 --- a/.gitignore +++ b/.gitignore @@ -13,8 +13,8 @@ bin/* .DS_Store # Vale will install modules in `.vale/style` and those should not be in version control -.vale/styles/* -!.vale/styles/config +.github/styles/* +!.github/styles/config # Test binary, built with `go test -c` *.test @@ -31,4 +31,4 @@ go.work dist/ .tmp .fabric -.fabric-lock.json \ No newline at end of file +.fabric-lock.json diff --git a/docs/_index.md b/docs/_index.md index a0569ad1..c29ab915 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -1,5 +1,6 @@ --- title: What is Fabric? +description: Fabric is a user-friendly open-source command-line tool for reporting workflow automation. Fabric comes with a versatile template language and a rich ecosystem of plugins. menuName: Docs type: docs weight: 1 @@ -7,11 +8,13 @@ weight: 1 # What's Fabric? -Fabric is an open-source CLI tool and a configuration language that codifies and automation of the content generation process. +Fabric is a user-friendly open-source command-line tool designed for reporting workflow automation. It comes with a versatile configuration language for reusable templates. -Fabric Configuration Language (FCL) allows users to define the document data requirements and content structure with human-readable configuration files. The files can be version-controlled, reused, and shared. +`fabric` CLI tool facilitates data collection from various sources and renders documents (reports, overviews, briefings, etc) from the templates in Fabric Configuration Language (FCL). -`fabric` is a reports-as-code tool that renders templates defined in the FCL files into Markdown documents. +[Fabric Configuration Language]({{< ref "language" >}}) offers a structured approach to defining data requirements and content structures. With its human-readable intuitive syntax and powerful features, FCL empowers users to create reusable modular templates. + +Together, Fabric CLI tool and FCL offer a comprehensive solution for organizations looking to formalize and streamline their content generation processes, enhancing their cyber-security and compliance efforts. ## Get started diff --git a/docs/cli.md b/docs/cli.md index 4a117f1a..e7066cd0 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,5 +1,6 @@ --- title: Fabric CLI +description: Fabric CLI is your gateway to Fabric's powerful features. Use `fabric` binary with commands like `install`, `data`, and `render`. Dive deeper with `fabric --help` to explore additional options and commands. Get started with Fabric CLI and unlock seamless document generation. type: docs weight: 20 --- @@ -8,7 +9,7 @@ weight: 20 The command line interface to Fabric is `fabric` CLI tool. -The core sub-commands are: +The core Fabric commands are: - `install` — installs all required plugins, listed in the [global configuration]({{< ref "language/configs.md#global-configuration" >}}). See [plugin installation docs]({{< ref "install.md#installing-plugins" >}}) for more details. - `data` — executes the data block and prints out prettified JSON to standard output. diff --git a/docs/content-providers.md b/docs/content-providers.md index 1c851f42..d0cb4afd 100644 --- a/docs/content-providers.md +++ b/docs/content-providers.md @@ -1,5 +1,6 @@ --- -title: Content Providers +title: Content providers +description: Explore a wide array of content providers through Fabric plugins. These powerful integrations enable the rendering of document content locally or via external APIs, covering various types including text, tables, graphs, code, and more. Enhance your document generation capabilities with Fabric's versatile content provider plugins. type: docs weight: 58 --- diff --git a/docs/data-sources.md b/docs/data-sources.md index 3d0244ba..6d57572b 100644 --- a/docs/data-sources.md +++ b/docs/data-sources.md @@ -1,5 +1,6 @@ --- -title: Data Sources +title: Data sources +description: Discover a diverse range of data sources within Fabric plugins. These integrations empower you to effortlessly load data from files, external services, APIs, and data storage systems. Simplify your data retrieval process and enhance your document generation workflow with Fabric's versatile data sources. type: docs weight: 52 --- diff --git a/docs/install.md b/docs/install.md index 30a5568c..fe66a047 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,5 +1,6 @@ --- title: Install +description: Learn how to install Fabric and its plugins to streamline your templating workflow. Fabric binaries for Windows, macOS, and Linux are available at the project's GitHub releases page. Simply download the appropriate release archive for your operating system, unpack it, and you're ready to go. type: docs weight: 10 code_blocks_no_wrap: true @@ -36,7 +37,7 @@ tar -xvzf ./fabric_darwin_arm64.tar.gz -C ./fabric-bin ## Installing plugins -Fabric relies on [the plugins]({{< ref "plugins.md" >}}) for implementing the integrations with various data sources, platforms, and services. Before the plugins can be used during the template rendering, they must be installed. Fabric's sub-command `install` can install the plugins automatically from the registry (`https://registry.blackstork.io`). +Fabric uses [plugins]({{< ref "plugins.md" >}}) that implementing integrations with various data sources, platforms, and services. Before the plugins can be used during template rendering, they must be installed. Fabric's sub-command `install` can install the plugins automatically from the registry (`https://registry.blackstork.io`). To install the plugins: @@ -53,7 +54,7 @@ To install the plugins: - **install the plugins**: run `install` sub-command to install the plugins. For example: - ```bash + ```text $ ./fabric install Mar 11 19:20:09.085 INF Searching plugin name=blackstork/elastic constraints=">=v0.0.1" Mar 11 19:20:09.522 INF Installing plugin name=blackstork/elastic version=0.4.0 @@ -62,7 +63,7 @@ To install the plugins: $ ``` -The plugins are downloaded and installed in `./fabric` folder or in the location specified in `cache_dir` in [the global configuration]({{< ref "language/configs.md#global-configuration" >}}). +The plugins are downloaded and installed in `./.fabric` folder or in the location specified in `cache_dir` in [the global configuration]({{< ref "language/configs.md#global-configuration" >}}). {{< hint note >}} diff --git a/docs/language/_index.md b/docs/language/_index.md index 4af0b262..167a31f1 100644 --- a/docs/language/_index.md +++ b/docs/language/_index.md @@ -1,5 +1,6 @@ --- title: Language +description: Fabric Configuration Language (FCL) drives Fabric's document generation capabilities. With FCL, users define data needs and template structures in .fabric files, streamlining content creation. Automate document production efficiently with Fabric and FCL. type: docs weight: 40 --- diff --git a/docs/language/configs.md b/docs/language/configs.md index 53e6b4f8..c05f016b 100644 --- a/docs/language/configs.md +++ b/docs/language/configs.md @@ -1,5 +1,6 @@ --- title: Configuration +description: Learn how to configure Fabric, data sources and content providers. type: docs weight: 20 --- diff --git a/docs/language/content-blocks.md b/docs/language/content-blocks.md index 8c6bca35..3c6c459d 100644 --- a/docs/language/content-blocks.md +++ b/docs/language/content-blocks.md @@ -1,5 +1,6 @@ --- title: Content Blocks +description: Learn how to use Fabric content blocks efficiently for building modular and reusable document templates. type: docs weight: 60 --- @@ -95,7 +96,7 @@ document "test-doc" { # The result of the query is stored in the `query_result` field in the context. # The context is available for the templating engine inside the `content.text` plugin. - text = "There are {{ .query_result }} items" + value = "There are {{ .query_result }} items" } content openai_text { diff --git a/docs/language/data-blocks.md b/docs/language/data-blocks.md index b37094cf..a624724b 100644 --- a/docs/language/data-blocks.md +++ b/docs/language/data-blocks.md @@ -1,5 +1,6 @@ --- title: Data Blocks +description: Learn how to use Fabric data blocks for defining data requirements for the templates. type: docs weight: 50 --- diff --git a/docs/language/documents.md b/docs/language/documents.md index 7f80062b..717828b2 100644 --- a/docs/language/documents.md +++ b/docs/language/documents.md @@ -1,5 +1,6 @@ --- title: Documents +description: Learn how to use document blocks to define document templates, building a content structure with the content blocks and setting data requirements with the data blocks. type: docs weight: 40 --- diff --git a/docs/language/references.md b/docs/language/references.md index d473b6de..5ab185c2 100644 --- a/docs/language/references.md +++ b/docs/language/references.md @@ -46,6 +46,8 @@ An anonymous `ref` block adopts a name of the referenced block. Since the final The `ref` block definition can include the attribute that would override the attributes provided in the original block. This is helpful if the block's behaviour needs adjustments per document. + diff --git a/docs/language/section-blocks.md b/docs/language/section-blocks.md index 4a24d878..9dddc4a7 100644 --- a/docs/language/section-blocks.md +++ b/docs/language/section-blocks.md @@ -1,5 +1,6 @@ --- title: Section Blocks +description: Learn how to use use section blocks to build modular and reusable content structures in your templates. type: docs weight: 70 --- diff --git a/docs/language/syntax.md b/docs/language/syntax.md index 3aff5cc0..c820ed18 100644 --- a/docs/language/syntax.md +++ b/docs/language/syntax.md @@ -1,5 +1,6 @@ --- title: Syntax +description: Explore the syntax of Fabric Configuration Language (FCL). Built upon the foundation of HCL, FCL offers simplicity, readability, and clarity. Learn about arguments and blocks, the fundamental components for crafting configurations with FCL. Dive into examples and understand the expressive and modular nature of FCL configurations. type: docs weight: 10 --- @@ -16,7 +17,8 @@ The arguments play a crucial role in assigning values to names within a block. A ```hcl ... { - query_string = "kibana.alert.severity:critical" + index = ".alerts-security.alerts-default" + query_string = "kibana.alert.severity:critical" } ``` @@ -27,12 +29,15 @@ The argument name, `query_string` in the snippet above, is allowed to contain le In the Fabric Configuration Language (FCL), a block serves as a versatile container defining configurations, data requirements, or content structures. An example is provided below: ```hcl -document "alerts_overview" { +document "test_document" { - content text { - text = "Static text" - } - ... + data inline { + foo = 42 + } + + content text { + value = "My custom static text" + } } ``` diff --git a/docs/plugins/_index.md b/docs/plugins/_index.md index f481e8b4..becd217a 100644 --- a/docs/plugins/_index.md +++ b/docs/plugins/_index.md @@ -1,20 +1,27 @@ --- title: Plugins +description: Discover the power of Fabric plugins, which implement various data sources and content providers to enhance your templating experience. Data sources enable loading data from files, external services, APIs, or data storage, while content providers render document content locally or via external APIs, supporting text, tables, graphs, code, and more. type: docs -weight: 60 +weight: 50 hideChildren: true --- # Plugins -Fabric relies on plugins for implementing integrations with data sources and content providers. The global configuration should specify all required plugins (see [Global configuration]({{< ref "../language/configs.md/#global-configuration" >}}) for the details). Additionally, some data sources and content providers themselves require configuration (for example, API keys, URLs, credentials, etc). +Fabric plugins implement various [data sources]({{< ref "data-sources.md" >}}) and [content providers]({{< ref "content-providers.md" >}}): -A plugin name consists of a namespace (a name of a plugin vendor) and a short name. For example, `blackstork/elastic` plugin built by [BlackStork](https://blackstork.io) implements Elasticsearch and Elastic Security Cases data sources. +- **data sources** are integrations responsible for loading data from the file, external service, API, or data storage. +- **content providers** render the document content locally or through the external API (like LLM). The content types include text, tables, graphs, code and other elements. -## Where to get the plugins +## Dependencies -Plugin releases are independent from Fabric releases. Plugins are distributed independently and have their own release cycle and version. -You can find a list of plugins released by BlackStork at the [Releases page](https://github.com/blackstork-io/fabric/releases) in Fabric GitHub. +The global configuration must include all required plugins (see [Global configuration]({{< ref "../language/configs.md/#global-configuration" >}})). A plugin name consists of a namespace (usually a vendor's name) and a short name. For example, [`blackstork/elastic`]({{< ref "./elastic/" >}}) plugin (built by BlackStork) implements [Elasticsearch data source]({{< ref "./elastic/data-sources/elasticsearch" >}}). + +## Installation + +Plugin releases are independent from Fabric releases and have their own release cycle and version. You can find a list of plugins released by BlackStork at the [Releases page](https://github.com/blackstork-io/fabric/releases) in Fabric GitHub repository. + +Required plugins can be downloaded and installed automatically with `fabric install` command. See [Installing plugins]({{< ref "../install.md#installing-plugins" >}}) for more details. ## Available plugins diff --git a/docs/tutorial.md b/docs/tutorial.md index 70e39fb5..c8833f48 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -1,5 +1,6 @@ --- title: Tutorial +description: Dive into Fabric tutorial to learn everything you need to know about using Fabric effectively. From the basics of FCL commands to advanced features such as data configurations, our tutorial provides clear, step-by-step instructions for building Fabric templates. Start improving your workflow with Fabric today. type: docs weight: 30 code_blocks_no_wrap: true @@ -28,7 +29,7 @@ Create a new `hello.fabric` file and define a simple template: document "greeting" { content text { - text = "Hello, Fabric!" + value = "Hello, Fabric!" } } @@ -61,19 +62,18 @@ document "greeting" { title = "The Greeting" content text { - text = "Hello, Fabric!" + value = "Hello, Fabric!" } } ``` {{< hint note >}} -`title` argument for `document` block is a syntactic sugar that Fabric translates into `content.text` block with `format_as` attribute set to `title`: +`title` argument for `document` block is a syntactic sugar that Fabric translates into `content.title` block: ```hcl -content text { - text = "The Greeting" - format_as = "title" +content title { + value = "The Greeting" } ``` @@ -111,13 +111,13 @@ document "greeting" { title = "The Greeting" content text { - text = "Hello, Fabric!" + value = "Hello, Fabric!" } content text { query = ".data.inline.solar_system.planets | length" - text = <<-EOT + value = <<-EOT There are {{ .query_result }} planets and {{ .data.inline.solar_system.moons_count }} moons in our solar system. EOT } @@ -174,13 +174,13 @@ document "greeting" { title = "The Greeting" content text { - text = "Hello, Fabric!" + value = "Hello, Fabric!" } content text { query = ".data.inline.solar_system.planets | length" - text = <<-EOT + value = <<-EOT There are {{ .query_result }} planets and {{ .data.inline.solar_system.moons_count }} moons in our solar system. EOT } @@ -266,13 +266,13 @@ document "greeting" { title = "The Greeting" content text { - text = "Hello, Fabric!" + value = "Hello, Fabric!" } content text { query = ".data.inline.solar_system.planets | length" - text = <<-EOT + value = <<-EOT There are {{ .query_result }} planets and {{ .data.inline.solar_system.moons_count }} moons in our solar system. EOT }