restructure spec and include metadata for docs (#118)

beeme1mr · web-flow · commit c18fb0eb75a1 · 2022-07-29T09:50:22.000-04:00
Signed-off-by: Michael Beemer &lt;michael.beemer@dynatrace.com&gt;
diff --git a/.markdownlint.yml b/.markdownlint.yml
@@ -6,3 +6,5 @@ MD033:
     - details
 MD024:
   siblings_only: true
+MD025:
+  front_matter_title: ""
diff --git a/Makefile b/Makefile
@@ -1,12 +1,9 @@
 IS_PYTHON_INSTALLED = $(shell which python >> /dev/null 2>&1; echo $$?)
 ALL_DOCS := $(shell find . -type f -name '*.md' -not -path './.github/*' -not -path './node_modules/*' | sort)
 
-parse: clean _check_python
+parse: _check_python
 	@python ./tools/specification_parser/specification_parser.py
 
-clean:
-	@find ./specification -name '*.json' -delete
-
 lint: node_modules
 	@python ./tools/specification_parser/lint_json_output.py specification.json
 	./node_modules/.bin/markdownlint --ignore node_modules/ --ignore tools/ **/*.md
@@ -25,13 +22,15 @@ _check_python:
 		&& echo "" \
 		&& exit 1; \
 		fi;
+
 .PHONY: markdown-toc
 markdown-toc: node_modules
 	@if ! npm ls markdown-toc; then npm ci; fi
 	@for f in $(ALL_DOCS); do \
 		if grep -q '<!-- tocstop -->' $$f; then \
 			echo markdown-toc: processing $$f; \
 			npx --no -- markdown-toc --bullets="-" --no-first-h1 --no-stripHeadingTags -i $$f || exit 1; \
+			npx --no -- prettier -w $$f; \
 		else \
 			echo markdown-toc: no TOC markers, skipping $$f; \
 		fi; \
diff --git a/specification/README.md b/specification/README.md
@@ -1,13 +1,20 @@
+---
+id: intro
+title: Intro
+description: An intro to the OpenFeature specification.
+sidebar_position: 0
+---
+
 # OpenFeature Specification
 
 ## Contents
 
 - [Glossary](./glossary.md)
 - [Types](./types.md)
-- [Evaluation API](./flag-evaluation.md)
-- [Providers](./providers.md)
-- [Evaluation Context](./evaluation-context.md)
-- [Hooks](./hooks.md)
+- [Evaluation API](./sections/01-flag-evaluation.md)
+- [Providers](./sections//02-providers.md)
+- [Evaluation Context](./sections/03-evaluation-context.md)
+- [Hooks](./sections/04-hooks.md)
 
 ## Conformance
 
diff --git a/specification/glossary.md b/specification/glossary.md
@@ -1,3 +1,9 @@
+---
+title: Glossary
+description: A list of terms used within the OpenFeature specification.
+sidebar_position: 1
+---
+
 # Glossary
 
 This document defines some terms that are used across this specification.
@@ -54,7 +60,7 @@ A developer who is setting up or configuring an application or service to use th
 
 ### Provider Author
 
-The maintainer of an API-compliant [provider](./providers.md) which implements the necessary interfaces required for flag evaluation.
+The maintainer of an API-compliant [provider](./sections/02-providers.md) which implements the necessary interfaces required for flag evaluation.
 
 ### Integration Author
 
@@ -86,7 +92,7 @@ A source-of-truth for flag values and rules. Flag management systems may include
 
 ### Provider
 
-An SDK-compliant implementation which resolves flag values from a particular flag management system, allowing the use of the [Evaluation API](./flag-evaluation.md#flag-evaluation) as an abstraction for the system in question.
+An SDK-compliant implementation which resolves flag values from a particular flag management system, allowing the use of the [Evaluation API](./sections/01-flag-evaluation.md#flag-evaluation) as an abstraction for the system in question.
 
 ### Integration
 
diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md
@@ -1,10 +1,16 @@
+---
+title: Flag Evaluation API
+description: The specification that defines the developer facing feature flag evaluation API.
+toc_max_heading_level: 4
+---
+
 # Flag Evaluation API
 
-**Status**: [Experimental](./README.md#document-statuses)
+**Status**: [Experimental](../README.md#document-statuses)
 
 ## Overview
 
-The `evaluation API` allows for the evaluation of feature flag values, independent of any flag control plane or vendor. In the absence of a [provider](./providers.md) the `evaluation API` uses the "No-op provider", which simply returns the supplied default flag value.
+The `evaluation API` allows for the evaluation of feature flag values, independent of any flag control plane or vendor. In the absence of a [provider](./02-providers.md) the `evaluation API` uses the "No-op provider", which simply returns the supplied default flag value.
 
 ### API Initialization and Configuration
 
@@ -23,7 +29,7 @@ It's important that multiple instances of the `API` not be active, so that state
 OpenFeature.setProvider(new MyProvider());
 ```
 
-See [provider](./providers.md) for details.
+See [provider](./02-providers.md) for details.
 
 #### Requirement 1.1.3
 
@@ -34,7 +40,7 @@ See [provider](./providers.md) for details.
 OpenFeature.addHooks([new MyHook()]);
 ```
 
-See [hooks](./hooks.md) for details.
+See [hooks](./04-hooks.md) for details.
 
 #### Requirement 1.1.4
 
@@ -45,7 +51,7 @@ See [hooks](./hooks.md) for details.
 OpenFeature.getProviderMetadata();
 ```
 
-See [provider](./providers.md) for details.
+See [provider](./02-providers.md) for details.
 
 #### Requirement 1.1.5
 
@@ -79,7 +85,7 @@ Clients may be created in critical code paths, and even per-request in server-si
 client.addHooks([new MyHook()]);
 ```
 
-See [hooks](./hooks.md) for details.
+See [hooks](./04-hooks.md) for details.
 
 #### Requirement 1.2.2
 
@@ -109,7 +115,7 @@ number myNumber = client.getNumberValue('number-flag', 75);
 MyStruct myStruct = client.getObjectValue<MyStruct>('structured-flag', { text: 'N/A', percentage: 75 }, evaluationContext, options);
 ```
 
-See [evaluation context](./evaluation-context.md) for details.
+See [evaluation context](./03-evaluation-context.md) for details.
 
 ##### Condition 1.3.2
 
@@ -126,7 +132,7 @@ GetIntValue(flag string, defaultValue int64, evalCtx EvaluationContext, options
 GetFloatValue(flag string, defaultValue float64, evalCtx EvaluationContext, options ...EvaluationOption) (float64, error)
 ```
 
-See [types](./types.md) for details.
+See [types](../types.md) for details.
 
 ##### Requirement 1.3.3
 
@@ -211,12 +217,12 @@ It's recommended to provide non-blocking mechanisms for flag evaluation, particu
 
 > The `evaluation options` structure's `hooks` field denotes an ordered collection of hooks that the client **MUST** execute for the respective flag evaluation, in addition to those already configured.
 
-See [hooks](./hooks.md) for details.
+See [hooks](./04-hooks.md) for details.
 
 #### Context Transformation
 
 ##### Requirement 1.6.1
 
 > The `client` **SHOULD** transform the `evaluation context` using the `provider's` `context transformer` function if one is defined, before passing the result of the transformation to the provider's flag resolution functions.
 
-See [context transformation](./providers.md#context-transformation) for details.
+See [context transformation](./02-providers.md#context-transformation) for details.
diff --git a/specification/sections/02-providers.md b/specification/sections/02-providers.md
@@ -1,12 +1,18 @@
+---
+title: Provider
+description: The specification that defines the responsibilities and behaviors of a provider.
+toc_max_heading_level: 4
+---
+
 # Provider
 
 ## Overview
 
 The `provider` API defines interfaces that Provider Authors can use to abstract a particular flag management system, thus enabling the use of the `evaluation API` by Application Authors.
 
-Providers are the "translator" between the flag evaluation calls made in application code, and the flag management system that stores flags and in some cases evaluates flags. At a minimum, providers should implement some basic evaluation methods which return flag values of the expected type. In addition, providers may transform the [evaluation context](evaluation-context.md) appropriately in order to be used in dynamic evaluation of their associated flag management system, provide insight into why evaluation proceeded the way it did, and expose configuration options for their associated flag management system. Hypothetical provider implementations might wrap a vendor SDK, embed an REST client, or read flags from a local file.
+Providers are the "translator" between the flag evaluation calls made in application code, and the flag management system that stores flags and in some cases evaluates flags. At a minimum, providers should implement some basic evaluation methods which return flag values of the expected type. In addition, providers may transform the [evaluation context](./03-evaluation-context.md) appropriately in order to be used in dynamic evaluation of their associated flag management system, provide insight into why evaluation proceeded the way it did, and expose configuration options for their associated flag management system. Hypothetical provider implementations might wrap a vendor SDK, embed an REST client, or read flags from a local file.
 
-![Provider](./assets/images/provider.png)
+![Provider](../assets/images/provider.png)
 
 ### Feature Provider Interface
 
@@ -31,7 +37,7 @@ provider.getMetadata().getName(); // "my-custom-provider"
 resolveBooleanValue(flagKey, defaultValue, context, options);
 ```
 
-see: [flag resolution structure](./types.md#flag-resolution), [flag value resolution](./glossary.md#flag-value-resolution)
+see: [flag resolution structure](../types.md#flag-resolution), [flag value resolution](../glossary.md#flag-value-resolution)
 
 ##### Condition 2.3
 
@@ -109,7 +115,7 @@ ResolutionDetails<MyStruct> resolveStructureValue(string flagKey, MyStruct defau
 
 Feature flag management systems often define structures representing arbitrary contextual data pertaining to the runtime, user, or application. The context transformer defines a simple interface to transform the OpenFeature `evaluation context` to such a structure, mapping values appropriately.
 
-See [evaluation context](./evaluation-context.md).
+See [evaluation context](./03-evaluation-context.md).
 
 ##### Requirement 2.10
 
@@ -130,7 +136,7 @@ class MyProvider implements Provider {
 }
 ```
 
-See [evaluation context](./evaluation-context.md), [flag evaluation](./flag-evaluation.md#flag-evaluation).
+See [evaluation context](./03-evaluation-context.md), [flag evaluation](./01-flag-evaluation.md#flag-evaluation).
 
 ##### Condition 2.11
 
diff --git a/specification/sections/03-evaluation-context.md b/specification/sections/03-evaluation-context.md
@@ -1,18 +1,24 @@
+---
+title: Evaluation Context
+description: The specification that defines the structure and expectations of evaluation context.
+toc_max_heading_level: 4
+---
+
 # Evaluation Context
 
-**Status**: [Experimental](./README.md#document-statuses)
+**Status**: [Experimental](../README.md#document-statuses)
 
 ## Overview
 
 The `evaluation context` provides ambient information for the purposes of flag evaluation. Contextual data may be used as the basis for targeting, including rule-based evaluation, overrides for specific subjects, or fractional flag evaluation.
 
-The context might contain information about the end-user, the application, the host, or any other ambient data that might be useful in flag evaluation. For example, a flag system might define rules that return a specific value based on the user's email address, locale, or the time of day. The context provides this information. The context can be optionally provided at evaluation, and mutated in [before hooks](./hooks.md).
+The context might contain information about the end-user, the application, the host, or any other ambient data that might be useful in flag evaluation. For example, a flag system might define rules that return a specific value based on the user's email address, locale, or the time of day. The context provides this information. The context can be optionally provided at evaluation, and mutated in [before hooks](./04-hooks.md).
 
 ### Fields
 
 NOTE: Field casing is not specified, and should be chosen in accordance with language idioms.
 
-see: [types](./types.md)
+see: [types](../types.md)
 
 #### Requirement 3.1
 
@@ -24,4 +30,4 @@ The targeting key uniquely identifies the subject (end-user, or client service)
 
 > The evaluation context **MUST** support the inclusion of custom fields, having keys of type `string`, and values of type `boolean | string | number | datetime | structure`.
 
-see: [structure](./types.md#structure), [datetime](./types.md#datetime)
+see: [structure](../types.md#structure), [datetime](../types.md#datetime)
diff --git a/specification/sections/04-hooks.md b/specification/sections/04-hooks.md
@@ -1,3 +1,9 @@
+---
+title: Hooks
+description: The specification that defines the expectations and life cycle of hooks.
+toc_max_heading_level: 4
+---
+
 # Hooks
 
 ## Overview
@@ -11,13 +17,13 @@ Hooks add their logic at any of four specific stages of flag evaluation:
 - `error`, immediately after an unsuccessful during flag evaluation
 - `finally` unconditionally after flag evaluation
 
-![Flag evaluation life cycle](./assets/images/life-cycle.png)
+![Flag evaluation life cycle](../assets/images/life-cycle.png)
 
-Hooks can be configured to run globally (impacting all flag evaluations), per client, or per flag evaluation invocation. Some example use-cases for hook include adding additional data to the [evaluation context](./evaluation-context.md), performing validation on the received flag value, providing data to telemetric tools, and logging errors.
+Hooks can be configured to run globally (impacting all flag evaluations), per client, or per flag evaluation invocation. Some example use-cases for hook include adding additional data to the [evaluation context](./03-evaluation-context.md), performing validation on the received flag value, providing data to telemetric tools, and logging errors.
 
 ### Definitions
 
-**Hook**: Application author/integrator-supplied logic that is called by the OpenFeature framework at a specific stage. **Stage**: An explicit portion of the flag evaluation lifecycle. e.g. `before` being "before the [resolution](./glossary.md#resolving-flag-values) is run. **Invocation**: A single call to evaluate a flag. `client.getBooleanValue(..)` is an invocation. **API**: The global API singleton.
+**Hook**: Application author/integrator-supplied logic that is called by the OpenFeature framework at a specific stage. **Stage**: An explicit portion of the flag evaluation lifecycle. e.g. `before` being "before the [resolution](../glossary.md#resolving-flag-values) is run. **Invocation**: A single call to evaluate a flag. `client.getBooleanValue(..)` is an invocation. **API**: The global API singleton.
 
 ### Hook context
 
@@ -157,7 +163,7 @@ In languages with try/catch semantics, this means that exceptions thrown in `err
 
 Before hooks can impact evaluation by various means, such as mutating the `evaluation context`. Therefore, an error in the `before` hooks is considered abnormal execution, and the default should be returned.
 
-### [Flag evaluation options](./types.md#evaluation-options)
+### [Flag evaluation options](../types.md#evaluation-options)
 
 Usage might look something like:
 
@@ -168,7 +174,7 @@ val = client.get_boolean_value('my-key', False, evaluation_options={
 })
 ```
 
-See: [Flag evaluation options](./flag-evaluation.md#)
+See: [Flag evaluation options](./01-flag-evaluation.md#)
 
 #### Requirement 4.5.1
 
diff --git a/specification/sections/_category_.json b/specification/sections/_category_.json
@@ -0,0 +1,9 @@
+{
+  "position": 3,
+  "label": "Sections",
+  "collapsible": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Specification Sections"
+  }
+}
diff --git a/specification/types.md b/specification/types.md
@@ -1,3 +1,9 @@
+---
+title: Types and Data Structures
+description: A description of types and data structures used within the OpenFeature specification.
+sidebar_position: 2
+---
+
 # Types and Data Structures
 
 ## Overview
@@ -26,7 +32,7 @@ A language primitive for representing a date and time, including timezone inform
 
 ### Evaluation Details
 
-A structure representing the result of the [flag evaluation process](./glossary.md#evaluating-flag-values), and made available in the [detailed flag resolution functions](./flag-evaluation.md#detailed-flag-evaluation), containing the following fields:
+A structure representing the result of the [flag evaluation process](./glossary.md#evaluating-flag-values), and made available in the [detailed flag resolution functions](./sections/01-flag-evaluation.md#detailed-flag-evaluation), containing the following fields:
 
 - flag key (string, required)
 - value (boolean | string | number | structure, required)
@@ -43,10 +49,10 @@ A structure which contains a subset of the fields defined in the `evaluation det
 - reason (string, optional)
 - variant (string, optional)
 
-\*NOTE: The `resolution details` structure is not exposed to the Application Author. It defines the data which Provider Authors must return when resolving the value of flags.
+> NOTE: The `resolution details` structure is not exposed to the Application Author. It defines the data which Provider Authors must return when resolving the value of flags.
 
 ### Evaluation Options
 
 A structure containing the following fields:
 
-- hooks (one or more [hooks](./hooks.md), optional)
+- hooks (one or more [hooks](./sections/04-hooks.md), optional)
