docs: give example categories better names

Author: mstream

docs/src/examples/README.generated.md

@@ -1,11 +1,11 @@
 # Examples
 
-- [Compatibility](#compatibility)
-- [Diff](#diff)
-- [Validation](#validation)
+- [JSON Schema Change Compatibility Checks](#json-schema-change-compatibility-checks)
+- [JSON Schema Difference Calculation](#json-schema-difference-calculation)
+- [JSON Values Validation](#json-values-validation)
 
 ---
-## Compatibility
+## JSON Schema Change Compatibility Checks
 ### ⌘ No JSON schema differences
 When there is not JSON schema differences, schema change is fully compatible.
 #### Input
@@ -178,7 +178,7 @@ forward
 ```
 
 ---
-## Diff
+## JSON Schema Difference Calculation
 ### ⌘ Comparing identical schemata
 When two identical schemata are compared, no difference should be found.
 #### Input
@@ -217,7 +217,7 @@ Any change in expected JSON value type should be accounted as a difference.
 ```
 
 ---
-## Validation
+## JSON Values Validation
 ### ⌘ A null value against a schema accepting only null values
 A null value conforms to the schema.
 #### Input

test/unit/Docs.purs

@@ -11,6 +11,7 @@ import Data.FoldableWithIndex
 import Data.Map (Map)
 import Data.Map as Map
 import Data.Maybe (Maybe(..))
+import Data.String (Pattern(..), Replacement(..))
 import Data.String as String
 import Effect (Effect)
 import Effect.Aff (launchAff_)
@@ -26,56 +27,44 @@ import Test.Spec.JsonSchema.Diff as Diff
 import Test.Spec.JsonSchema.Validation as Validation
 import Test.Types (Example)
 
-main ∷ Effect Unit
-main = do
-  args ← Process.argv
-  examples ← selectExamples $ args !! 2
+data Category
+  = Compatibility
+  | Diff
+  | Validation
 
-  launchAff_
-    $ FS.writeTextFile UTF8 "docs/src/examples/README.generated.md"
-    $ printExamples
-    $ groupExamplesByCategory examples
-  where
-  selectExamples ∷ Maybe String → Effect (Array PrintableExample)
-  selectExamples = case _ of
-    Nothing →
-      pure allExamples
-    Just moduleName →
-      case moduleName of
-        "Codec" →
-          pure $ makePrintable "Codec" <$> Codec.examples
-        "Compatibility" →
-          pure $ makePrintable "Compatibility" <$>
-            Compatibility.examples
-        "Diff" →
-          pure $ makePrintable "Diff" <$> Diff.examples
-        "Parsing" →
-          pure $ makePrintable "Parsing" <$> Parsing.examples
-        "Printing" →
-          pure $ makePrintable "Printing" <$> Printing.examples
-        "Validation" →
-          pure $ makePrintable "Validation" <$> Validation.examples
-        _ →
-          throw $ "Unknown module name \"" <> moduleName <> "\""
+derive instance Eq Category
+derive instance Ord Category
+
+renderCategory ∷ Category → String
+renderCategory = case _ of
+  Compatibility →
+    "JSON Schema Change Compatibility Checks"
+  Diff →
+    "JSON Schema Difference Calculation"
+  Validation →
+    "JSON Values Validation"
 
-  allExamples ∷ Array PrintableExample
-  allExamples =
-    (makePrintable "Codec" <$> Codec.examples)
-      <> (makePrintable "Compatibility" <$> Compatibility.examples)
-      <> (makePrintable "Diff" <$> Diff.examples)
-      <> (makePrintable "Parsing" <$> Parsing.examples)
-      <> (makePrintable "Printing" <$> Printing.examples)
-      <> (makePrintable "Validation" <$> Validation.examples)
+main ∷ Effect Unit
+main = launchAff_
+  $ FS.writeTextFile UTF8 "docs/src/examples/README.generated.md"
+  $ printExamples
+  $ groupExamplesByCategory examples
+  where
+  examples ∷ Array PrintableExample
+  examples =
+    (makePrintable Compatibility <$> Compatibility.examples)
+      <> (makePrintable Diff <$> Diff.examples)
+      <> (makePrintable Validation <$> Validation.examples)
 
 type PrintableExample =
-  { category ∷ String
+  { category ∷ Category
   , description ∷ String
   , input ∷ String
   , output ∷ String
   , title ∷ String
   }
 
-makePrintable ∷ ∀ i o. String → Example i o → PrintableExample
+makePrintable ∷ ∀ i o. Category → Example i o → PrintableExample
 makePrintable category example =
   { category
   , description: example.description
@@ -88,7 +77,7 @@ groupExamplesByCategory
   ∷ ∀ f
   . Foldable f
   ⇒ f PrintableExample
-  → Map String (Array PrintableExample)
+  → Map Category (Array PrintableExample)
 groupExamplesByCategory = foldl
   ( \acc example →
       Map.insertWith
@@ -101,7 +90,7 @@ groupExamplesByCategory = foldl
 
 printExamples
   ∷ ∀ f
-  . FoldableWithIndex String f
+  . FoldableWithIndex Category f
   ⇒ f (Array PrintableExample)
   → String
 printExamples examplesByCategory =
@@ -114,19 +103,23 @@ printExamples examplesByCategory =
       )
     <> foldMapWithIndex printCategory examplesByCategory
   where
-  printTableOfContents ∷ Array String → String
+  printTableOfContents ∷ Array Category → String
   printTableOfContents = (_ <> "\n")
     <<< foldMap printTableOfContentsEntry
 
-  printTableOfContentsEntry ∷ String → String
+  printTableOfContentsEntry ∷ Category → String
   printTableOfContentsEntry category =
-    "- [" <> category <> "](#" <> String.toLower category <> ")\n"
+    "- ["
+      <> renderCategory category
+      <> "](#"
+      <> (formatAnchor $ renderCategory category)
+      <> ")\n"
 
-  printCategory ∷ String → Array PrintableExample → String
+  printCategory ∷ Category → Array PrintableExample → String
   printCategory category examples =
     "---\n"
       <> "## "
-      <> category
+      <> renderCategory category
       <> "\n"
       <> foldMap printExample examples
 
@@ -141,3 +134,7 @@ printExamples examplesByCategory =
       <> "\n#### Output\n"
       <> output
       <> "\n\n"
+
+  formatAnchor ∷ String → String
+  formatAnchor = String.replaceAll (Pattern " ") (Replacement "-")
+    <<< String.toLower