Writing and maintaining Website Style Guides (and Documentation) is hard work that often result in Dead Style Guides.
Automatically generated documentation is clearly the way to go. Which tools are available in Elm?
First there is the documentation-format used to document modules. The concept is the one of writing comments before each function directly inside the code. Bringing the code and the documentation together is a great approach because we are lazy and we don’t want to spend time looking for the related documentation somewhere else.
This is the same reason why we bring css and html inside the code. elements-style, for example, in the new alpha version, is bringing all css inline.
Similar approach, of transforming comments into documentation, is the one used by KSS and many other tools for automatically generating Style Guides. This is an example of Style Guide made with KSS.
Other documentation can be generated from the code. Elm is not an introspective language so one possibility would be to read and parse the source code directly (or use some un-Elmy module). I have been done it for Json.Decode to document the API.
We could otherwise use some sort of Code Generation, such as elm-cog or json-to-elm.
The possibilities are many.
This is a quick test that I made to document a logo http://guupa.com/elm-logo/indexElm.html (Coca-Cola version: http://guupa.com/elm-logo/indexCocacola.html)
In this case to create the documentation I added a file for introspections like this:
module LogoElmIntrospection exposing (..)import LogoElm as LogologoTypes : List Logo.Type
logoTypes =
[ Logo.Colorful
, Logo.Color Logo.Orange
, Logo.Color Logo.Green
, Logo.Color Logo.LightBlue
, Logo.Color Logo.Blue
, Logo.Color Logo.White
, Logo.Color Logo.Black
]logoTypeDefault : Logo.Type
logoTypeDefault =
Logo.ColorfulconvertLogoTypeToString : Logo.Type -> String
convertLogoTypeToString logoType =
case logoType of
Logo.Color color ->
"Color " ++ convertLogoColorToString colorLogo.Colorful ->
"Colorful"convertLogoColorToString : Logo.Color -> String
convertLogoColorToString colorType =
case colorType of
Logo.Orange ->
"Orange" Logo.Green ->
"Green" Logo.LightBlue ->
"LightBlue" Logo.Blue ->
"Blue" Logo.White ->
"White" Logo.Black ->
"Black"
It is not as DRY as it could be because all these info were already inside logoElm.elm:
module LogoElm exposing (..)import Html
import Svg
import Svg.Attributestype Type
= Color Color
| Colorfultype alias Size =
Inttype Color
= Orange
| Green
| LightBlue
| Blue
| White
| Blackratio : Float
ratio =
-- Width / Height
1cssRgb : Color -> String
cssRgb color =
case color of
Orange ->
"#f0ad00" Green ->
"#7fd13b" LightBlue ->
"#60b5cc" Blue ->
"#5a6378" White ->
"#fff" Black ->
"#000"logo : Type -> Size -> Html.Html msg
logo type_ height =
let
f =
Svg.Attributes.fill d =
Svg.Attributes.d p =
Svg.path c =
case type_ of
Colorful ->
{ c1 = cssRgb Orange
, c2 = cssRgb Green
, c3 = cssRgb LightBlue
, c4 = cssRgb Blue
} Color c ->
{ c1 = cssRgb c
, c2 = cssRgb c
, c3 = cssRgb c
, c4 = cssRgb c
}
in
Svg.svg
[ Svg.Attributes.version "1"
, Svg.Attributes.viewBox "0 0 323 323"
, Svg.Attributes.height <| toString height
, Svg.Attributes.width <| toString <| floor <| toFloat
height * ratio
]
[ p [ f c.c1, d "M162 153l70-70H92zm94 94l67 67V179z" ] []
, p [ f c.c2, d "M9 0l70 70h153L162 0zm238 85l77 76-77 77-
76-77z" ] []
, p [ f c.c3, d "M323 144V0H180zm-161 27L9 323h305z" ] []
, p [ f c.c4, d "M153 162L0 9v305z" ] []
]
