Initial seed commit with documentation

Author: Mpdreamz

.editorconfig

@@ -0,0 +1,209 @@
+root=true
+
+[*]
+charset = utf-8
+indent_style = tab
+indent_size = 4
+# Spell checker configuration
+spelling_exclusion_path = "./build/exclusion.dic"
+
+[*.{fs,fsx,cs,vb}]
+file_header_template=Licensed to Elasticsearch B.V under one or more agreements.\nElasticsearch B.V licenses this file to you under the Apache 2.0 License.\nSee the LICENSE file in the project root for more information
+
+[*.{fs,fsx}]
+indent_style = space
+indent_size = 4
+
+[*.{md,markdown,json,js,yml,csproj,fsproj,targets,targets,props}]
+indent_style = space
+indent_size = 2
+
+# Dotnet code style settings:
+[*.{cs,vb}]
+trim_trailing_whitespace=true
+insert_final_newline=true
+# ---
+# naming conventions https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-naming-conventions
+# currently not supported in Rider/Resharper so not using these for now
+# ---
+
+# ---
+# language conventions https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference#language-conventions
+
+# Sort using and Import directives with System.* appearing first
+dotnet_sort_system_directives_first = true
+
+# Style rules
+# https://docs.microsoft.com/en-us/dotnet/fundamentals/code-analysis/style-rules/naming-rules?view=vs-2017
+
+# Constants always pascal case
+dotnet_naming_rule.constants_should_be_pascal_case.symbols  = consts
+dotnet_naming_rule.constants_should_be_pascal_case.style    = consts
+dotnet_naming_rule.constants_should_be_pascal_case.severity = suggestion
+
+dotnet_naming_symbols.consts.applicable_kinds           = field
+dotnet_naming_symbols.consts.applicable_accessibilities = *
+dotnet_naming_symbols.consts.required_modifiers = const
+
+dotnet_naming_style.consts.capitalization = pascal_case
+
+# Non-public static fields always pascal case
+dotnet_naming_rule.non_public_static_fields_should_be_pascal_case.symbols  = non_public_static_fields
+dotnet_naming_rule.non_public_static_fields_should_be_pascal_case.style    = non_public_static_fields
+dotnet_naming_rule.non_public_static_fields_should_be_pascal_case.severity = suggestion
+
+dotnet_naming_symbols.non_public_static_fields.applicable_kinds           = field
+dotnet_naming_symbols.non_public_static_fields.applicable_accessibilities = private,protected,internal,protected_internal,private_protected
+dotnet_naming_symbols.non_public_static_fields.required_modifiers = static
+
+dotnet_naming_style.non_public_static_fields.capitalization = pascal_case
+
+# Non-private readonly fields are pascal case
+dotnet_naming_rule.non_private_readonly_fields_should_be_pascal_case.severity = suggestion
+dotnet_naming_rule.non_private_readonly_fields_should_be_pascal_case.symbols = non_private_readonly_fields
+dotnet_naming_rule.non_private_readonly_fields_should_be_pascal_case.style = non_private_readonly_fields
+
+dotnet_naming_symbols.non_private_readonly_fields.applicable_kinds = field
+dotnet_naming_symbols.non_private_readonly_fields.applicable_accessibilities = public,protected,internal,protected_internal,private_protected
+dotnet_naming_symbols.non_private_readonly_fields.required_modifiers = readonly
+
+dotnet_naming_style.non_private_readonly_fields.capitalization = pascal_case
+
+# Private instance fields are camel case prefixed underscore
+dotnet_naming_rule.private_fields_should_be_camelcase_prefix_underscore.symbols  = private_fields
+dotnet_naming_rule.private_fields_should_be_camelcase_prefix_underscore.style    = private_fields
+dotnet_naming_rule.private_fields_should_be_camelcase_prefix_underscore.severity = suggestion
+
+dotnet_naming_symbols.private_fields.applicable_kinds           = field
+dotnet_naming_symbols.private_fields.applicable_accessibilities = private
+
+dotnet_naming_style.private_fields.capitalization = camel_case
+dotnet_naming_style.private_fields.required_prefix = _
+
+# Locals and parameters are camel case
+dotnet_naming_rule.locals.severity = suggestion
+dotnet_naming_rule.locals.symbols = locals
+dotnet_naming_rule.locals.style = locals
+
+dotnet_naming_symbols.locals.applicable_kinds = parameter, local
+
+dotnet_naming_style.locals.capitalization = camel_case
+
+# Local functions are pascal case
+dotnet_naming_rule.local_functions.severity = suggestion
+dotnet_naming_rule.local_functions.symbols = local_functions
+dotnet_naming_rule.local_functions.style = local_functions
+
+dotnet_naming_symbols.local_functions.applicable_kinds = local_function
+
+dotnet_naming_style.local_functions.capitalization = pascal_case
+
+# Public members always pascal case
+dotnet_naming_rule.public_members_should_be_pascal_case.symbols  = public_members
+dotnet_naming_rule.public_members_should_be_pascal_case.style    = public_members
+dotnet_naming_rule.public_members_should_be_pascal_case.severity = suggestion
+
+dotnet_naming_symbols.public_members.applicable_kinds           = property,method,field,event,delegate
+dotnet_naming_symbols.public_members.applicable_accessibilities = public
+
+dotnet_naming_style.public_members.capitalization = pascal_case
+
+dotnet_style_qualification_for_field = false:error
+dotnet_style_qualification_for_property = false:error
+dotnet_style_qualification_for_method = false:error
+dotnet_style_qualification_for_event = false:error
+
+# Use language keywords instead of framework type names for type references
+dotnet_style_predefined_type_for_locals_parameters_members = true:error
+dotnet_style_predefined_type_for_member_access = true:error
+
+# Suggest more modern language features when available
+dotnet_style_object_initializer = true:error
+dotnet_style_collection_initializer = true:error
+dotnet_style_explicit_tuple_names = true:error
+dotnet_style_prefer_inferred_anonymous_type_member_names = true:error
+dotnet_style_prefer_inferred_tuple_names = true:error
+dotnet_style_coalesce_expression = true:error
+dotnet_style_null_propagation = true:error
+
+dotnet_style_require_accessibility_modifiers = for_non_interface_members:error
+dotnet_style_readonly_field = true:error
+
+# CSharp code style settings:
+[*.cs]
+# Prefer "var" everywhere
+csharp_style_var_for_built_in_types = true:error
+csharp_style_var_when_type_is_apparent = true:error
+csharp_style_var_elsewhere = true:error
+
+csharp_style_expression_bodied_methods = true:suggestion
+csharp_style_expression_bodied_constructors = true:suggestion
+csharp_style_expression_bodied_operators = true:suggestion
+csharp_style_expression_bodied_properties = true:suggestion
+csharp_style_expression_bodied_indexers = true:suggestion
+csharp_style_expression_bodied_accessors = true:suggestion
+
+# Suggest more modern language features when available
+csharp_style_pattern_matching_over_is_with_cast_check = true:error
+csharp_style_pattern_matching_over_as_with_null_check = true:error
+csharp_style_inlined_variable_declaration = true:error
+csharp_style_deconstructed_variable_declaration = true:error
+csharp_style_pattern_local_over_anonymous_function = true:error
+csharp_style_throw_expression = true:error
+csharp_style_conditional_delegate_call = true:error
+
+csharp_prefer_braces = false:warning
+csharp_preferred_modifier_order = public,private,protected,internal,static,extern,new,virtual,abstract,sealed,override,readonly,unsafe,volatile,async:error
+
+# ---
+# formatting conventions https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference#formatting-conventions
+
+# Newline settings (Allman yo!)
+csharp_new_line_before_open_brace = all
+csharp_new_line_before_else = true
+csharp_new_line_before_catch = true
+csharp_new_line_before_finally = true
+csharp_new_line_before_members_in_object_initializers = true
+# just a suggestion do to our JSON tests that use anonymous types to 
+# represent json quite a bit (makes copy paste easier).
+csharp_new_line_before_members_in_anonymous_types = true
+csharp_new_line_between_query_expression_clauses = true
+
+# Indent
+csharp_indent_case_contents = true
+csharp_indent_switch_labels = true
+csharp_space_after_cast = false
+csharp_space_after_keywords_in_control_flow_statements = true
+csharp_space_between_method_declaration_parameter_list_parentheses = false
+csharp_space_between_method_call_parameter_list_parentheses = false
+
+#Wrap
+csharp_preserve_single_line_statements = false
+csharp_preserve_single_line_blocks = true
+
+# Resharper
+resharper_csharp_braces_for_lock=required_for_multiline
+resharper_csharp_braces_for_using=required_for_multiline
+resharper_csharp_braces_for_while=required_for_multiline
+resharper_csharp_braces_for_foreach=required_for_multiline
+resharper_csharp_braces_for_for=required_for_multiline
+resharper_csharp_braces_for_fixed=required_for_multiline
+resharper_csharp_braces_for_ifelse=required_for_multiline
+
+resharper_csharp_accessor_owner_body=expression_body
+
+resharper_redundant_case_label_highlighting=do_not_show
+resharper_redundant_argument_default_value_highlighting=do_not_show
+resharper_explicit_caller_info_argument_highlighting=hint
+
+dotnet_diagnostic.IDE0057.severity = none
+
+[*.{sh,bat,ps1}]
+trim_trailing_whitespace=true
+insert_final_newline=true
+
+[*.sh]
+end_of_line = lf
+
+[{LICENSE,NOTICE}]
+end_of_line = lf

.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "*.*.*"
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{steps.deployment.outputs.page_url}}
+    steps:
+      - id: repo-basename
+        run: 'echo "value=`basename ${{ github.repository }}`" >> $GITHUB_OUTPUT'
+      - uses: actions/checkout@v4
+      - name: Setup Pages
+        id: pages
+        uses: actions/[email protected]
+      - name: Build documentation
+        uses: elastic/docs-builder@main
+        with:
+          prefix: '${{ steps.repo-basename.outputs.value }}'
+      - name: Upload artifact
+        uses: actions/[email protected]
+        with:
+          path: .artifacts/docs/html
+          
+      - name: Deploy artifact
+        id: deployment
+        uses: actions/[email protected] 

.github/workflows/pr.yml

@@ -0,0 +1,20 @@
+name: PR
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  packages: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: elastic/docs-builder@main
+        name: Build documentation

.gitignore

@@ -0,0 +1 @@
+.artifacts

.vscode/tasks.json

@@ -0,0 +1,27 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Build Documentation (Incremental)",
+            "type": "shell",
+            "command": "docker run -v \"./.git:/app/.git\" -v \"./docs:/app/docs\" -v \"./.artifacts:/app/.artifacts\" ghcr.io/elastic/docs-builder:edge",
+            "problemMatcher": [],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "Serve Documentation",
+            "type": "shell",
+            "command": "docker run -v \"./.git:/app/.git\" -v \"./docs:/app/docs\" -v \"./.artifacts:/app/.artifacts\" --expose 8080 ghcr.io/elastic/docs-builder:edge serve",
+            "problemMatcher": [],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        }
+    ]
+}

docs/source/_ext/rejoin.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+from docutils import nodes
+
+from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxDirective, SphinxRole, directives
+from sphinx.util.typing import ExtensionMetadata
+
+def rejoin_text(text: str, split_by: str, join_by: str) -> str:
+    return join_by.join(text.lower().split(split_by))
+
+class RejoinRole(SphinxRole):
+    """A role to split by a string and rejoin by another string !"""
+
+    def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]:
+        node = nodes.inline(text=rejoin_text(self.text, ' ', '-'))
+        return [node], []
+
+class RejoinDirective(SphinxDirective):
+    """A directive to split by a string and rejoin by another string !"""
+
+    required_arguments = 1
+    has_content = True
+    FROM_OPTION = 'from'
+    TO_OPTION = 'to'
+    optional_arguments = 2
+    option_spec = {
+        FROM_OPTION: directives.unchanged,
+        TO_OPTION: directives.unchanged
+    }
+
+    def run(self) -> list[nodes.Node]:
+        label = self.arguments[0]
+        text = ''.join(self.content)
+        fr = self.options[self.FROM_OPTION]
+        to = self.options[self.TO_OPTION]
+        rejoined_text = rejoin_text(text, fr, to)
+        converted_text = f"{label} : {rejoined_text}"
+        paragraph_node = nodes.inline(text=converted_text)
+        return [paragraph_node]
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.add_role('rejoin', RejoinRole())
+    app.add_directive('rejoin', RejoinDirective)
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }