mdoc 0.3.1.1 → 0.3.2.0

raw patch · 21 files changed

+154/−56 lines, 21 filesPVP: major bump suggested

API removals or changes: PVP suggests a major version bump

API changes (from Hackage documentation)

Files

• data/man1.template +11/−8
• data/man5.template +22/−4
• examples/crontab.5 +3/−0
• examples/docker.1 +5/−0
• examples/examplerc.5 +9/−0
• examples/person.5 +8/−0
• mdoc.cabal +1/−1
• src/Autodocodec/Schema/Mdoc.hs +1/−0
• src/Env/Mdoc.hs +1/−0
• src/Mdoc/Data/Described.hs +3/−17
• src/Mdoc/Data/List.hs +7/−1
• src/Mdoc/Data/Optionality.hs +8/−0
• src/Mdoc/Data/Page.hs +13/−1
• src/Mdoc/Examples/Docker.hs +8/−8
• src/Mdoc/Examples/OptEnvConf.hs +7/−4
• src/OptEnvConf/Mdoc.hs +18/−5
• src/Options/Applicative/Mdoc.hs +1/−0
• test/Autodocodec/Schema/MdocSpec.hs +2/−2
• test/Mdoc/Data/ConfigSpec.hs +13/−4
• test/Mdoc/ExamplesSpec.hs +1/−1
• test/Mdoc/Test/Render.hs +12/−0

@@ -39,10 +39,13 @@ The options are as follows: .Bl -tag -width {{{page.options.width}}} {{#page.options.items}}-.It {{{head}}}-{{#body}}-{{{body}}}-{{/body}}+.It {{{item}}}+{{#help}}+{{{help}}}+{{#optionality.default}}+(default: {{{.}}})+{{/optionality.default}}+{{/help}} {{/page.options.items}} .El {{/page.options}}@@ -63,10 +66,10 @@ .Nm : .Bl -tag -width {{{page.environment.width}}} {{#page.environment.items}}-.It {{{head}}}-{{#body}}-{{{body}}}-{{/body}}+.It {{{item}}}+{{#help}}+{{{help}}}+{{/help}} {{/page.environment.items}} .El {{/page.environment}}

@@ -18,10 +18,28 @@ {{/page.prologue}} .Bl -tag -width {{{page.configs.width}}} {{#page.configs.items}}-.It {{{head}}}-{{#body}}-{{{body}}}-{{/body}}+.It {{{item}}}+{{#help}}+{{{help}}}+{{/help}}+{{#optionality.required}}+(required)+{{/optionality.required}}+{{^optionality.required}}+{{#optionality.default}}+(optional, default: {{{.}}})+{{/optionality.default}}+{{^optionality.default}}+(optional)+{{/optionality.default}}+{{/optionality.required}}+{{#example}}+.Pp+Example:+.Bd -literal -offset indent+{{{.}}}+.Ed+{{/example}} {{/page.configs.items}} .El {{#page.epilogue}}

@@ -15,8 +15,11 @@ .Bl -tag -width indent .It Cm bar.bat : Ar number Ns [] Bar's bat is better than that+(required) .It Cm bar.baz : Ar boolean Bar's baz of bazzle+(required) .It Cm foo : Ar string Foo's the fooing of fooers+(required) .El

@@ -41,18 +41,23 @@ Daemon socket to connect to .It Fl l Ar string , Fl Fl log\-level= Ns Ar string Set the logging level ("debug", "info", "warn", "error", "fatal")+(default: "info") .It Fl v , Fl Fl version Print version information and quit .It Fl Fl config= Ns Ar string Location of client config files+(default: "~/.docker") .It Fl Fl tls Use TLS; implied by \-\-tlsverify .It Fl Fl tlscacert= Ns Ar string Trust certs signed only by this CA+(default: "~/.docker/ca.pem") .It Fl Fl tlscert= Ns Ar string Path to TLS certificate file+(default: "~/.docker/cert.pem") .It Fl Fl tlskey= Ns Ar string Path to TLS key file+(default: "~/.docker/key.pem") .It Fl Fl tlsverify Use TLS and verify the remote .El

@@ -13,6 +13,15 @@ .Bl -tag -width indent .It Cm debug : Ar boolean Enable debug+(optional, default: False)+.Pp+Example:+.Bd -literal -offset indent+# enable debug+debug: true+.Ed .It Cm file : Ar string+(required) .It Cm verbose : Ar boolean+(optional, default: False) .El

@@ -13,18 +13,26 @@ .Bl -tag -width indent .It Cm address : Ar object Their address+(optional) .It Cm address.city : Ar string The city+(required) .It Cm address.postalCode : Ar string The postal code+(required) .It Cm address.state : Ar string The state+(required) .It Cm address.street : Ar string The street+(required) .It Cm age : Ar number Their age+(required) .It Cm hobbies : Ar string Ns [] Their hobbies+(optional) .It Cm name : Ar string Their name+(required) .El

@@ -1,6 +1,6 @@ cabal-version:      1.18 name:               mdoc-version:            0.3.1.1+version:            0.3.2.0 license:            AGPL-3 license-file:       COPYING maintainer:         Pat Brisbin

@@ -136,6 +136,7 @@                 _ -> Optional             , multiple = False             , help = textToMdoc =<< mcomment+            , example = Nothing             }         ]   ObjectAllOfSchema os -> concatMap simplifyObjectSchema $ toList os

@@ -31,4 +31,5 @@     , optionality = maybe Required Defaulted (varfHelpDef v)     , multiple = False     , help = textToMdoc . pack =<< varfHelp v+    , example = Nothing     }

@@ -16,11 +16,9 @@  import Mdoc.Prelude -import Data.Aeson (object, (.=)) import Data.Function (on) import Mdoc.Data.Optionality import Mdoc.Optics-import Mdoc.Pretty import Mdoc.Syntax  data Described a = Described@@ -28,8 +26,10 @@   , optionality :: Optionality   , multiple :: Bool   , help :: Maybe Mdoc+  , example :: Maybe Mdoc   }   deriving stock (Foldable, Functor, Generic, Show, Traversable)+  deriving anyclass (ToJSON)  instance Eq a => Eq (Described a) where   (==) = (==) `on` (.item)@@ -37,21 +37,6 @@ instance Ord a => Ord (Described a) where   compare = comparing (.item) -instance Pretty a => Pretty (Described a) where-  pretty d =-    vsep-      $ catMaybes-        [ Just $ ".It" <+> pretty d.item-        , pretty <$> d.help-        ]--instance ToJSON a => ToJSON (Described a) where-  toJSON d =-    object-      [ "head" .= d.item-      , "body" .= d.help-      ]- -- | Describe an item as 'Required', singular, without help required :: a -> Described a required item =@@ -60,6 +45,7 @@     , optionality = Required     , multiple = False     , help = Nothing+    , example = Nothing     }  -- | Concat a described list into a single item

@@ -73,7 +73,13 @@   getHead :: Value -> Text   getHead v = fromMaybe "" $ do     Object km <- pure v-    String t <- KeyMap.lookup "head" km++    -- Look for various ways we name the item head in context+    String t <-+      KeyMap.lookup "item" km+        <|> KeyMap.lookup "head" km+        <|> KeyMap.lookup "name" km+     pure t    go :: [Text] -> Text

@@ -12,8 +12,16 @@  import Mdoc.Prelude +import Data.Aeson (object, (.=))+ data Optionality   = Optional   | Required   | Defaulted String   deriving stock (Eq, Ord, Show)++instance ToJSON Optionality where+  toJSON = \case+    Optional -> object ["required" .= False]+    Required -> object ["required" .= True]+    Defaulted s -> object ["required" .= False, "default" .= s]

@@ -1,3 +1,5 @@+{-# OPTIONS_GHC -Wno-ambiguous-fields #-}+ -- | -- -- Module      : Mdoc.Data.Page@@ -36,6 +38,7 @@ import Mdoc.Data.EnvVar import Mdoc.Data.List (ByItem, Indent, List) import Mdoc.Data.List qualified as List+import Mdoc.Data.Optionality import Mdoc.Data.Positional import Mdoc.Data.Synopsis (Synopsis (..)) import Mdoc.Data.Synopsis qualified as Synopsis@@ -56,7 +59,16 @@   deriving (Monoid, Semigroup) via Generically Page  addSwitch :: Described Flag -> Page -> Page-addSwitch = addPositional . fmap PositionalSwitch+addSwitch = addPositional . fmap PositionalSwitch . tweakOptionality+ where+  -- Avoid showing a bunch of (default: False) for switches+  tweakOptionality :: Described a -> Described a+  tweakOptionality d =+    d+      { optionality = case d.optionality of+          Defaulted {} -> Optional+          o -> o+      }  addOption :: Described Option -> Page -> Page addOption = addPositional . fmap PositionalOption

@@ -17,17 +17,17 @@ {- FOURMOLU_DISABLE -} dockerOpt :: OptEnvConf.Parser () dockerOpt = void $ (,,,,,,,,,,,)-  <$> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "config",                          OptEnvConf.metavar "string", OptEnvConf.help "Location of client config files", OptEnvConf.value "/home/patrick/.docker"])+  <$> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "config",                          OptEnvConf.metavar "string", OptEnvConf.help "Location of client config files", OptEnvConf.value "~/.docker"])   <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.short 'c', OptEnvConf.long "context",   OptEnvConf.metavar "string", OptEnvConf.help "Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with \"docker context use\")"])-  <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.short 'D', OptEnvConf.long "debug",                                  OptEnvConf.help "Enable debug mode"])+  <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.short 'D', OptEnvConf.long "debug",                            OptEnvConf.help "Enable debug mode"])   <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.short 'H', OptEnvConf.long "host",      OptEnvConf.metavar "string", OptEnvConf.help "Daemon socket to connect to"])   <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.short 'l', OptEnvConf.long "log-level", OptEnvConf.metavar "string", OptEnvConf.help "Set the logging level (\"debug\", \"info\", \"warn\", \"error\", \"fatal\")", OptEnvConf.value "info"])-  <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.long "tls",                                            OptEnvConf.help "Use TLS; implied by --tlsverify"])-  <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlscacert",                       OptEnvConf.metavar "string", OptEnvConf.help "Trust certs signed only by this CA", OptEnvConf.value "/home/patrick/.docker/ca.pem"])-  <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlscert",                         OptEnvConf.metavar "string", OptEnvConf.help "Path to TLS certificate file", OptEnvConf.value "/home/patrick/.docker/cert.pem"])-  <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlskey",                          OptEnvConf.metavar "string", OptEnvConf.help "Path to TLS key file", OptEnvConf.value "/home/patrick/.docker/key.pem"])-  <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.long "tlsverify",                                      OptEnvConf.help "Use TLS and verify the remote"])-  <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.short 'v', OptEnvConf.long "version",                  OptEnvConf.help "Print version information and quit"])+  <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.long "tls",                                                    OptEnvConf.help "Use TLS; implied by --tlsverify"])+  <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlscacert",                       OptEnvConf.metavar "string", OptEnvConf.help "Trust certs signed only by this CA", OptEnvConf.value "~/.docker/ca.pem"])+  <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlscert",                         OptEnvConf.metavar "string", OptEnvConf.help "Path to TLS certificate file", OptEnvConf.value "~/.docker/cert.pem"])+  <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlskey",                          OptEnvConf.metavar "string", OptEnvConf.help "Path to TLS key file", OptEnvConf.value "~/.docker/key.pem"])+  <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.long "tlsverify",                                              OptEnvConf.help "Use TLS and verify the remote"])+  <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.short 'v', OptEnvConf.long "version",                          OptEnvConf.help "Print version information and quit"])   <*> OptEnvConf.commands     [ OptEnvConf.command "run"  "Create and run a new container from an image" runOpt     , OptEnvConf.command "exec" "Execute a command in a running container" execOpt

@@ -9,7 +9,7 @@ module Mdoc.Examples.OptEnvConf   ( conf5   , example1-  , example5+  , examplerc5   ) where  import Mdoc.Prelude@@ -50,8 +50,8 @@     & (<> OptEnvConf.getPage exampleParser)     & name "example" "opt-env-conf example" -example5 :: Named-example5 =+examplerc5 :: Named+examplerc5 =   mempty     & (<> OptEnvConf.getPage exampleParser)     & setSynopsis@@ -66,7 +66,10 @@ {- FOURMOLU_DISABLE -} exampleParser :: OptEnvConf.Parser (Bool, Bool, Text, Text, [Text]) exampleParser = (,,,,)-  <$> OptEnvConf.setting [OptEnvConf.env "DEBUG", OptEnvConf.conf "debug", OptEnvConf.switch True, OptEnvConf.long "debug", OptEnvConf.help "Enable debug", OptEnvConf.value False]+  <$> OptEnvConf.setting [OptEnvConf.env "DEBUG", OptEnvConf.conf "debug", OptEnvConf.switch True, OptEnvConf.long "debug", OptEnvConf.help "Enable debug", OptEnvConf.value False+      , OptEnvConf.example "# enable debug"+      , OptEnvConf.example "debug: true"+      ]   <*> OptEnvConf.setting [OptEnvConf.conf "verbose", OptEnvConf.switch True, OptEnvConf.short 'v', OptEnvConf.long "verbose", OptEnvConf.value False]   <*> OptEnvConf.setting [OptEnvConf.env "INPUT", OptEnvConf.option, OptEnvConf.reader OptEnvConf.str, OptEnvConf.short 'i', OptEnvConf.metavar "INPUT"]   <*> OptEnvConf.setting [OptEnvConf.conf "file", OptEnvConf.argument, OptEnvConf.reader OptEnvConf.str, OptEnvConf.metavar "FILE"]

@@ -26,6 +26,7 @@ import Mdoc.Data.Option import Mdoc.Data.Optionality import Mdoc.Data.Page+import Mdoc.Syntax import OptEnvConf (CommandDoc (..), Parser, SetDoc (..)) import OptEnvConf.Args (Dashed (..)) import OptEnvConf.Doc (AnyDocs (..), parserDocs)@@ -107,7 +108,7 @@     modify (+ 1)     pure $ f index acc $ Left cdocs   AnyDocsAnd ds -> foldM (foldSetDocsM f) acc ds-  AnyDocsOr ds -> foldM (foldSetDocsM fAsMultiple) acc ds+  AnyDocsOr ds -> foldM (foldSetDocsM fForOr) acc ds   AnyDocsSingle Nothing -> pure acc -- hidden/internal   AnyDocsSingle (Just d) -> do     index <- get@@ -120,12 +121,24 @@         , optionality = maybe Required Defaulted (setDocDefault d)         , multiple = False         , help = textToMdoc . pack =<< setDocHelp d+        , example = exampleMdoc <$> nonEmpty (setDocExamples d)         }  where-  -- This is suspect, but it seems we can't distinguish if the Or is being used-  -- to indicate some/many or optionality. We'll just treat it as both since it-  -- passes our current tests.-  fAsMultiple i m e = f i m $ second (\d -> d {optionality = Optional, multiple = True}) e+  -- AnyDocsOr is used for Empty, Alt, and Many. The former two map to+  -- optionality while the latter maps to multiple. We don't have enough+  -- information to know what's what, so we treat such cases as both optional+  -- and multiple. I guess that's what OptEnvConf's own `--help` rendering must+  -- do, since it operates on the same lossy `AnyDocs` structure.+  fForOr i m e = f i m $ (<$> e) $ \d ->+    d+      { optionality = case d.optionality of+          Required -> Optional+          o -> o+      , multiple = True+      }++exampleMdoc :: NonEmpty String -> Mdoc+exampleMdoc = Mdoc . map (TextLine . esc . pack) . toList  dashedFlags :: [Dashed] -> Maybe Flag dashedFlags = fmap go . nonEmpty

@@ -121,6 +121,7 @@             , optionality = maybe Required Defaulted (O.optShowDefault o)             , multiple = False             , help = textToMdoc =<< docToText (O.optHelp o)+            , example = Nothing             }       O.Internal -> pure acc       O.Hidden -> pure acc

@@ -154,7 +154,7 @@                        ]  schemaDoc :: JSONSchema -> Doc ann-schemaDoc = vsep . map pretty . getConfigs Nothing+schemaDoc = prettyDescribeds . getConfigs Nothing  schemaDocAt :: NonEmpty String -> JSONSchema -> Doc ann-schemaDocAt keys = vsep . map pretty . getConfigs (Just keys)+schemaDocAt keys = prettyDescribeds . getConfigs (Just keys)

@@ -32,9 +32,18 @@             , optionality = Required             , multiple = False             , help = Just $ Mdoc [TextLine "Push to git remote"]+            , example =+                textToMdoc+                  $ mconcat+                    [ "# disable pushing\n"+                    , "git:\n"+                    , "  push: false\n"+                    , "\n"+                    ]             } -    config-      `shouldRender` [ ".It Cm git.push : Ar boolean"-                     , "Push to git remote"-                     ]+    renderPlain (prettyDescribed config)+      `shouldBe` mconcat+        [ ".It Cm git.push : Ar boolean\n"+        , "Push to git remote"+        ]

@@ -41,7 +41,7 @@   it "pass.1" $ exampleGolden man1 pass1 1   it "docker.1" $ exampleGolden man1 docker1 1   it "conf.5" $ exampleGolden man5 conf5 5-  it "example.5" $ exampleGolden man5 example5 5+  it "examplerc.5" $ exampleGolden man5 examplerc5 5   it "person.5" $ exampleGolden man5 person5 5  exampleGolden :: Template -> Named -> Int -> IO (Golden Mdoc)

@@ -8,11 +8,15 @@ -- Portability : POSIX module Mdoc.Test.Render   ( shouldRender+  , prettyDescribeds+  , prettyDescribed+  , renderPlain   ) where  import Mdoc.Prelude  import Data.Text qualified as T+import Mdoc.Data.Described import Mdoc.Pretty import Test.Hspec @@ -21,3 +25,11 @@   renderPlain (pretty a) `shouldBe` T.intercalate "\n" lns  infix 1 `shouldRender`++prettyDescribeds :: Pretty a => [Described a] -> Doc ann+prettyDescribeds = vsep . map prettyDescribed++-- | @Described@ is rendered to JSON and formatted in-template, so we don't want+-- to have a misleading 'Pretty' instance. So we use this instead.+prettyDescribed :: Pretty a => Described a -> Doc ann+prettyDescribed d = vsep $ catMaybes [Just $ ".It" <+> pretty d.item, pretty <$> d.help]