diff --git a/data/man1.template b/data/man1.template --- a/data/man1.template +++ b/data/man1.template @@ -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}} diff --git a/data/man5.template b/data/man5.template --- a/data/man5.template +++ b/data/man5.template @@ -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}} diff --git a/examples/crontab.5 b/examples/crontab.5 --- a/examples/crontab.5 +++ b/examples/crontab.5 @@ -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 diff --git a/examples/docker.1 b/examples/docker.1 --- a/examples/docker.1 +++ b/examples/docker.1 @@ -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 diff --git a/examples/examplerc.5 b/examples/examplerc.5 --- a/examples/examplerc.5 +++ b/examples/examplerc.5 @@ -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 diff --git a/examples/person.5 b/examples/person.5 --- a/examples/person.5 +++ b/examples/person.5 @@ -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 diff --git a/mdoc.cabal b/mdoc.cabal --- a/mdoc.cabal +++ b/mdoc.cabal @@ -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 diff --git a/src/Autodocodec/Schema/Mdoc.hs b/src/Autodocodec/Schema/Mdoc.hs --- a/src/Autodocodec/Schema/Mdoc.hs +++ b/src/Autodocodec/Schema/Mdoc.hs @@ -136,6 +136,7 @@ _ -> Optional , multiple = False , help = textToMdoc =<< mcomment + , example = Nothing } ] ObjectAllOfSchema os -> concatMap simplifyObjectSchema $ toList os diff --git a/src/Env/Mdoc.hs b/src/Env/Mdoc.hs --- a/src/Env/Mdoc.hs +++ b/src/Env/Mdoc.hs @@ -31,4 +31,5 @@ , optionality = maybe Required Defaulted (varfHelpDef v) , multiple = False , help = textToMdoc . pack =<< varfHelp v + , example = Nothing } diff --git a/src/Mdoc/Data/Described.hs b/src/Mdoc/Data/Described.hs --- a/src/Mdoc/Data/Described.hs +++ b/src/Mdoc/Data/Described.hs @@ -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 diff --git a/src/Mdoc/Data/List.hs b/src/Mdoc/Data/List.hs --- a/src/Mdoc/Data/List.hs +++ b/src/Mdoc/Data/List.hs @@ -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 diff --git a/src/Mdoc/Data/Optionality.hs b/src/Mdoc/Data/Optionality.hs --- a/src/Mdoc/Data/Optionality.hs +++ b/src/Mdoc/Data/Optionality.hs @@ -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] diff --git a/src/Mdoc/Data/Page.hs b/src/Mdoc/Data/Page.hs --- a/src/Mdoc/Data/Page.hs +++ b/src/Mdoc/Data/Page.hs @@ -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 diff --git a/src/Mdoc/Examples/Docker.hs b/src/Mdoc/Examples/Docker.hs --- a/src/Mdoc/Examples/Docker.hs +++ b/src/Mdoc/Examples/Docker.hs @@ -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 diff --git a/src/Mdoc/Examples/OptEnvConf.hs b/src/Mdoc/Examples/OptEnvConf.hs --- a/src/Mdoc/Examples/OptEnvConf.hs +++ b/src/Mdoc/Examples/OptEnvConf.hs @@ -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"] diff --git a/src/OptEnvConf/Mdoc.hs b/src/OptEnvConf/Mdoc.hs --- a/src/OptEnvConf/Mdoc.hs +++ b/src/OptEnvConf/Mdoc.hs @@ -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 diff --git a/src/Options/Applicative/Mdoc.hs b/src/Options/Applicative/Mdoc.hs --- a/src/Options/Applicative/Mdoc.hs +++ b/src/Options/Applicative/Mdoc.hs @@ -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 diff --git a/test/Autodocodec/Schema/MdocSpec.hs b/test/Autodocodec/Schema/MdocSpec.hs --- a/test/Autodocodec/Schema/MdocSpec.hs +++ b/test/Autodocodec/Schema/MdocSpec.hs @@ -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) diff --git a/test/Mdoc/Data/ConfigSpec.hs b/test/Mdoc/Data/ConfigSpec.hs --- a/test/Mdoc/Data/ConfigSpec.hs +++ b/test/Mdoc/Data/ConfigSpec.hs @@ -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" + ] diff --git a/test/Mdoc/ExamplesSpec.hs b/test/Mdoc/ExamplesSpec.hs --- a/test/Mdoc/ExamplesSpec.hs +++ b/test/Mdoc/ExamplesSpec.hs @@ -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) diff --git a/test/Mdoc/Test/Render.hs b/test/Mdoc/Test/Render.hs --- a/test/Mdoc/Test/Render.hs +++ b/test/Mdoc/Test/Render.hs @@ -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]