Fix how we display default/example/description of an option (#86)

* description is now converted to html at import time
* default/example should now realize what is an non-value and what is
  "None" (as string) value

fixes #69
fixes #67

scripts/import-channel

@@ -1,5 +1,5 @@
 #! /usr/bin/env nix-shell
-#! nix-shell -i python3 -p python3 python3Packages.requests python3Packages.click python3Packages.click-log python3Packages.elasticsearch python3Packages.boto3 python3Packages.tqdm
+#! nix-shell -i python3 -p python3 python3Packages.requests python3Packages.click python3Packages.click-log python3Packages.elasticsearch python3Packages.boto3 python3Packages.tqdm python3Packages.pypandoc
 
 # develop:
 # $ nix-shell -p python3Packages.black python3Packages.mypy python3Packages.flake8
@@ -11,19 +11,21 @@
 # $ nix-shell -p python3Packages.flake8 --command "flake8 --ignore E501,E265 import-channel"
 
 import boto3
+import botocore
+import botocore.client
+import xml.etree.ElementTree
 import click
-import logging
 import click_log
 import elasticsearch
 import elasticsearch.helpers
-import requests
 import json
+import logging
 import os.path
+import pypandoc
+import requests
 import shlex
 import subprocess
 import tqdm
-import botocore.client
-import botocore
 
 logger = logging.getLogger("import-channel")
 click_log.basic_config(logger)
@@ -382,20 +384,42 @@ def get_options(evaluation):
 
     def gen():
         for name, option in options:
+            default = option.get("default")
+            if default is not None:
+                default = str(default)
+
+
             example = option.get("example")
-            if (
+            if example is not None:
-                example
+                if (type(example) == dict and example.get("_type") == "literalExample"):
-                and type(example) == dict
+                    example = str(example["text"])
-                and example.get("_type") == "literalExample"
+                else:
-            ):
+                    example = str(example)
-                example = str(example["text"])
+
+            description = option.get("description")
+            if description is not None:
+                xml_description = (
+                        f"<xml xmlns:xlink=\"http://www.w3.org/1999/xlink\">"
+                        f"<para>{description}</para>"
+                        f"</xml>"
+                    )
+                # we first check if there are some xml elements before using pypandoc
+                # since pypandoc calls are quite slow
+                root = xml.etree.ElementTree.fromstring(xml_description)
+                if len(root.find('para').getchildren()) > 0:
+                    description = pypandoc.convert_text(
+                        xml_description,
+                        "html",
+                        format="docbook",
+                    )
+
             yield dict(
                 type="option",
                 option_name=name,
-                option_description=option.get("description"),
+                option_description=description,
                 option_type=option.get("type"),
-                option_default=str(option.get("default")),
+                option_default=default,
-                option_example=str(example),
+                option_example=example,
                 option_source=option.get("declarations", [None])[0],
             )
 

src/Page/Options.elm

@@ -55,11 +55,11 @@ type alias Model =
 
 type alias ResultItemSource =
     { name : String
-    , description : String
+    , description : Maybe String
-    , type_ : String
+    , type_ : Maybe String
-    , default : String
+    , default : Maybe String
-    , example : String
+    , example : Maybe String
-    , source : String
+    , source : Maybe String
     }
 
 
@@ -182,28 +182,45 @@ viewResultItemDetails item =
                 [ href <| githubUrlPrefix ++ (value |> String.replace ":" "#L") ]
                 [ text <| value ]
 
-        withDefault wrapWith value =
+        wrapped wrapWith value =
             case value of
                 "" ->
-                    text default
+                    wrapWith <| "\"" ++ value ++ "\""
-
-                "None" ->
-                    text default
 
                 _ ->
                     wrapWith value
     in
     dl [ class "dl-horizontal" ]
         [ dt [] [ text "Description" ]
-        , dd [] [ withDefault asText item.source.description ]
+        , dd []
+            [ item.source.description
+                |> Maybe.withDefault default
+                |> asText
+            ]
         , dt [] [ text "Default value" ]
-        , dd [] [ withDefault asCode item.source.default ]
+        , dd []
+            [ item.source.default
+                |> Maybe.withDefault default
+                |> wrapped asCode
+            ]
         , dt [] [ text "Type" ]
-        , dd [] [ withDefault asCode item.source.type_ ]
+        , dd []
+            [ item.source.type_
+                |> Maybe.withDefault default
+                |> asCode
+            ]
         , dt [] [ text "Example value" ]
-        , dd [] [ withDefault asCode item.source.example ]
+        , dd []
+            [ item.source.example
+                |> Maybe.withDefault default
+                |> wrapped asCode
+            ]
         , dt [] [ text "Declared in" ]
-        , dd [] [ withDefault asGithubLink item.source.source ]
+        , dd []
+            [ item.source.source
+                |> Maybe.withDefault default
+                |> asGithubLink
+            ]
         ]
 
 
@@ -392,8 +409,8 @@ decodeResultItemSource : Json.Decode.Decoder ResultItemSource
 decodeResultItemSource =
     Json.Decode.map6 ResultItemSource
         (Json.Decode.field "option_name" Json.Decode.string)
-        (Json.Decode.field "option_description" Json.Decode.string)
+        (Json.Decode.field "option_description" (Json.Decode.nullable Json.Decode.string))
-        (Json.Decode.field "option_type" Json.Decode.string)
+        (Json.Decode.field "option_type" (Json.Decode.nullable Json.Decode.string))
-        (Json.Decode.field "option_default" Json.Decode.string)
+        (Json.Decode.field "option_default" (Json.Decode.nullable Json.Decode.string))
-        (Json.Decode.field "option_example" Json.Decode.string)
+        (Json.Decode.field "option_example" (Json.Decode.nullable Json.Decode.string))
-        (Json.Decode.field "option_source" Json.Decode.string)
+        (Json.Decode.field "option_source" (Json.Decode.nullable Json.Decode.string))