Merge pull request #733 from input-output-hk/plt-3312-help-text

PLT-3312 More help text

marlowe-chain-sync/marlowe-chain-indexer/Options.hs

@@ -8,6 +8,7 @@ import Data.Maybe (fromMaybe)
 import Data.Text (Text)
 import Language.Marlowe.Runtime.ChainIndexer.NodeClient (CostModel (..))
 import qualified Options.Applicative as O
+import Prettyprinter
 import System.Environment (lookupEnv)
 import Text.Read (readMaybe)
 
@@ -209,6 +210,30 @@ parseOptions defaultNetworkId defaultSocketPath defaultDatabaseUri version = O.i
     infoMod =
       mconcat
         [ O.fullDesc
-        , O.progDesc "Chain indexer for Marlowe Runtime."
-        , O.header "marlowe-chain-indexer : a chain indexer for the Marlowe Runtime."
+        , O.progDescDoc $ Just description
+        , O.header "marlowe-chain-indexer: Chain indexer for the Marlowe Runtime."
         ]
+
+description :: Doc ann
+description =
+  concatWith
+    (\a b -> a <> line <> line <> b)
+    [ vcat
+        [ "The chain indexer for the Marlowe Runtime. This component connects to a local"
+        , "Cardano Node and follows the chain. It copies a subset of the information"
+        , "contained in every block to a postgresql database. This database can be queried"
+        , "by downstream components, such as marlowe-chain-sync."
+        ]
+    , vcat
+        [ "There should only be one instance of marlowe-chain-indexer writing data to a"
+        , "given chain database. There is no need to run multiple indexers. If you would"
+        , "like to scale runtime services, it is recommended to deploy a postgres replica"
+        , "cluster, run one indexer to populate it, and as many marlowe-chain-sync"
+        , "instances as required to read from it."
+        ]
+    , vcat
+        [ "Before running the indexer, the database must be created and migrated using"
+        , "sqitch. The migration plan and SQL scripts are included in the source code"
+        , "folder for marlowe-chain-indexer."
+        ]
+    ]

marlowe-chain-sync/marlowe-chain-sync.cabal

@@ -251,6 +251,7 @@ executable marlowe-chain-indexer
     , mtl >=2.2 && <3
     , optparse-applicative
     , postgresql-libpq ^>=0.9
+    , prettyprinter
     , text ^>=1.2
     , time >=1.9 && <2
     , transformers ^>=0.5.6
@@ -284,5 +285,6 @@ executable marlowe-chain-sync
     , network >=3.1 && <4
     , optparse-applicative
     , postgresql-libpq ^>=0.9
+    , prettyprinter
     , text ^>=1.2
     , unliftio ^>=0.2.1

marlowe-chain-sync/marlowe-chain-sync/Options.hs

@@ -7,6 +7,7 @@ import Cardano.Api (NetworkId (..), NetworkMagic (..))
 import Data.Maybe (fromMaybe)
 import Network.Socket (HostName, PortNumber)
 import qualified Options.Applicative as O
+import Prettyprinter
 import System.Environment (lookupEnv)
 import Text.Read (readMaybe)
 
@@ -219,6 +220,41 @@ parseOptions defaultNetworkId defaultSocketPath defaultDatabaseUri defaultHost d
     infoMod =
       mconcat
         [ O.fullDesc
-        , O.progDesc "Chain sync server for Marlowe Runtime."
-        , O.header "marlowe-chain-sync : a chain sync server for the Marlowe Runtime."
+        , O.progDescDoc $ Just description
+        , O.header "marlowe-chain-indexer: Chain query and sync server for the Marlowe Runtime."
         ]
+
+description :: Doc ann
+description =
+  concatWith
+    (\a b -> a <> line <> line <> b)
+    [ vcat
+        [ "The chain query engine for the Marlowe Runtime. This component exposes three"
+        , "protocols through which downstream components can interact with the blockchain."
+        , "These are: chain seek, chain query, and chain command."
+        ]
+    , vcat
+        [ "The chain seek protocol is a synchronization protocol which allows the follower"
+        , "to jump directly ahead to blocks that match a particular query."
+        ]
+    , vcat
+        [ "The chain query protocol allows various network parameters and UTxO state to be"
+        , "queried."
+        ]
+    , vcat
+        [ "The chain command protocol allows transactions to be submitted to the connected node."
+        ]
+    , vcat
+        [ "marlowe-chain-sync relies on the connected database being migrated and populated by"
+        , "a marlowe-chain-indexer instance. While marlowe-chain-sync can operate without"
+        , "marlowe-chain-indexer running, marlowe-chain-indexer must be run first to insert"
+        , "the genesis UTxOs before marlowe-chain-sync can be used, and relies on"
+        , "marlowe-chain-indexer to keep the database up-to-date."
+        ]
+    , vcat
+        [ "marlowe-chain-sync is designed to scale horizontally. That is to say, multiple"
+        , "instances can run in parallel to scale with demand. A typical setup for this would"
+        , "involve running multiple marlowe-chain-sync instances in front of a load balancer"
+        , "against a scalable postgres replica cluster being populated by a single chain indexer."
+        ]
+    ]

marlowe-runtime/changelog.d/20231020_085010_jhbertra_plt_3312_help_text.md

@@ -0,0 +1,3 @@
+### Added
+
+- More documentation in --help text

marlowe-runtime/marlowe-contract/Main.hs

@@ -45,16 +45,18 @@ import Options.Applicative (
   help,
   helper,
   info,
+  infoOption,
   long,
   metavar,
   option,
-  progDesc,
+  progDescDoc,
   short,
   showDefault,
   strOption,
   value,
  )
 import Paths_marlowe_runtime
+import Prettyprinter
 
 main :: IO ()
 main = do
@@ -151,6 +153,7 @@ getOptions = do
   execParser $
     info
       ( helper
+          <*> versionOption
           <*> ( Options
                   <$> hostParser
                   <*> portParser
@@ -171,6 +174,11 @@ getOptions = do
       )
       infoMod
   where
+    versionOption =
+      infoOption
+        ("marlowe-contract " <> showVersion version)
+        (long "version" <> help "Show version.")
+
     hostParser =
       strOption $
         mconcat
@@ -314,6 +322,42 @@ getOptions = do
     infoMod =
       mconcat
         [ fullDesc
-        , progDesc "Contract storage service for Marlowe Runtime"
-        , header "marlowe-contract : a contract storage service for the Marlowe Runtime."
+        , progDescDoc $ Just description
+        , header "marlowe-tx: Transaction creation server for the Marlowe Runtime."
+        ]
+
+description :: Doc ann
+description =
+  concatWith
+    (\a b -> a <> line <> line <> b)
+    [ vcat
+        [ "The contract storage service for the Marlowe Runtime. It manages a crucial component of the"
+        , "Marlowe runtime: the contract store. The contract store is a content-addressable store of"
+        , "contracts indexed by their hashes. Contracts can refer to sub-contracts via their hashes via"
+        , "the MerkleizedCase construct. The contract store is used to store the continuations of a contract"
+        , "after it has been merkleized (a process which recursively replaces Case constructs with MerkleizedCase"
+        , "constructs). It is also used to lookup continuations when applying inputs to a merkleized contract."
+        , "This component exposes three protocols: marlowe load, marlowe transfer, and contract store query."
+        ]
+    , vcat
+        [ "The marlowe load protocol is one way to import a contract incrementally into the store. It presents"
+        , "a stack-based interface for pushing a contract depth-first into the store."
+        ]
+    , vcat
+        [ "The marlowe transfer protocol is the other way to import a contract incrementally into the store."
+        , "It leverages the Marlowe object model to allow bundles of user-defined marlowe objects to be streamed"
+        , "into the store. marlowe-contract will link the contract on-the-fly, merkleize the intermediate contracts,"
+        , "and build the final contract incrementally. This protocol is generally more efficient and flexible than"
+        , "Marlowe load because it allows duplicate sub-contracts to be pre-abstracted by the user. It also supports"
+        , "An export mode which will stream the closure of a contract from the store to the client as a Marlowe object"
+        , "bundle. This can be used to export continuations from the store and share it with other contract stores."
+        ]
+    , vcat
+        [ "The contract store query protocol provides queries that allow clients to fetch contracts by their hash,"
+        , "fetch the adjacency or closure sets of a contract, or merkleize an input."
+        ]
+    , vcat
+        [ "marlowe-contract depends on a marlowe-sync and marlowe-chain-sync instance to run automatic"
+        , "Garbage collection. These must both be running in order for marlowe-contract to run."
         ]
+    ]

marlowe-runtime/marlowe-indexer/Main.hs

@@ -45,16 +45,18 @@ import Options.Applicative (
   help,
   helper,
   info,
+  infoOption,
   long,
   metavar,
   option,
-  progDesc,
+  progDescDoc,
   short,
   showDefault,
   strOption,
   value,
  )
 import Paths_marlowe_runtime (version)
+import Prettyprinter
 import UnliftIO (MonadUnliftIO (..), throwIO)
 
 main :: IO ()
@@ -118,7 +120,7 @@ data Options = Options
   }
 
 getOptions :: IO Options
-getOptions = execParser $ info (helper <*> parser) infoMod
+getOptions = execParser $ info (helper <*> versionOption <*> parser) infoMod
   where
     parser =
       Options
@@ -128,6 +130,11 @@ getOptions = execParser $ info (helper <*> parser) infoMod
         <*> databaseUriParser
         <*> httpPortParser
 
+    versionOption =
+      infoOption
+        ("marlowe-indexer " <> showVersion version)
+        (long "version" <> help "Show version.")
+
     chainSeekPortParser =
       option auto $
         mconcat
@@ -180,6 +187,29 @@ getOptions = execParser $ info (helper <*> parser) infoMod
     infoMod =
       mconcat
         [ fullDesc
-        , progDesc "Contract indexing service for Marlowe Runtime"
-        , header "marlowe-indexer : a contract indexing service for the Marlowe Runtime."
+        , progDescDoc $ Just description
+        , header "marlowe-indexer: Contract indexing service for the Marlowe Runtime."
+        ]
+
+description :: Doc ann
+description =
+  concatWith
+    (\a b -> a <> line <> line <> b)
+    [ vcat
+        [ "The contract indexer for the Marlowe Runtime. It connects to a marlowe-chain-sync"
+        , "instance using both the chain seek and chain query protocol. It scans the chain for"
+        , "Marlowe contract transactions and saves them in a postgresql database. This database"
+        , "can be queried by downstream components, such as marlowe-sync."
+        ]
+    , vcat
+        [ "There should only be one instance of marlowe-indexer writing data to a given marlowe"
+        , "database. There is no need to run multiple indexers. If you would like to scale runtime"
+        , "services, it is recommended to deploy a postgres replica cluster, run one indexer to"
+        , "populate it, and as many marlowe-sync instances as required to read from it."
+        ]
+    , vcat
+        [ "Before running the indexer, the database must be created and migrated using"
+        , "sqitch. The migration plan and SQL scripts are included in the source code"
+        , "folder for marlowe-indexer."
         ]
+    ]

marlowe-runtime/marlowe-proxy/Main.hs

@@ -32,16 +32,18 @@ import Options.Applicative (
   help,
   helper,
   info,
+  infoOption,
   long,
   metavar,
   option,
-  progDesc,
+  progDescDoc,
   short,
   showDefault,
   strOption,
   value,
  )
 import Paths_marlowe_runtime
+import Prettyprinter
 
 main :: IO ()
 main = do
@@ -123,6 +125,7 @@ getOptions = do
   execParser $
     info
       ( helper
+          <*> versionOption
           <*> ( Options
                   <$> hostParser
                   <*> portParser
@@ -143,6 +146,11 @@ getOptions = do
       )
       infoMod
   where
+    versionOption =
+      infoOption
+        ("marlowe-proxy " <> showVersion version)
+        (long "version" <> help "Show version.")
+
     hostParser =
       strOption $
         mconcat
@@ -188,6 +196,19 @@ getOptions = do
     infoMod =
       mconcat
         [ fullDesc
-        , progDesc "API proxy service for Marlowe Runtime"
-        , header "marlowe-proxy : an API proxy service for the Marlowe Runtime."
+        , progDescDoc $ Just description
+        , header "marlowe-proxy: The API gateway server for the Marlowe Runtime."
+        ]
+
+description :: Doc ann
+description =
+  concatWith
+    (\a b -> a <> line <> line <> b)
+    [ vcat
+        [ "The API gateway server for the Marlowe Runtime. It exposes all the public protocols of the"
+        , "Marlowe runtime as a single multiplexed protocol: marlowe sync, marlowe header sync, marlowe"
+        , "bulk sync, marlowe query, marlowe transaction job, marlowe load, marlowe transfer, and contract"
+        , "store query. Please consult the help text for the individual services for detailed descriptions"
+        , "of these individual protocols."
         ]
+    ]

marlowe-runtime/marlowe-runtime.cabal

@@ -666,6 +666,7 @@ executable marlowe-indexer
     , nonempty-containers ^>=0.3.4
     , optparse-applicative ^>=0.17
     , postgresql-libpq ^>=0.9
+    , prettyprinter
     , text ^>=1.2
     , unliftio ^>=0.2.1
 
@@ -697,6 +698,7 @@ executable marlowe-sync
     , network >=3.1 && <4
     , optparse-applicative ^>=0.17
     , postgresql-libpq ^>=0.9
+    , prettyprinter
     , text ^>=1.2
     , unliftio ^>=0.2.1
 
@@ -723,6 +725,8 @@ executable marlowe-tx
     , marlowe-runtime:{marlowe-runtime, contract-api, tx, tx-api} ==0.0.5
     , network >=3.1 && <4
     , optparse-applicative ^>=0.17
+    , prettyprinter
+    , prettyprinter-ansi-terminal
     , text ^>=1.2
     , time
 
@@ -749,6 +753,7 @@ executable marlowe-contract
     , marlowe-runtime:{config, contract, contract-api, sync-api} ==0.0.5
     , network >=3.1 && <4
     , optparse-applicative ^>=0.17
+    , prettyprinter
     , text ^>=1.2
     , time
     , typed-protocols ^>=0.1
@@ -775,6 +780,7 @@ executable marlowe-proxy
     , marlowe-runtime:{config, contract-api, discovery-api, history-api, proxy, proxy-api, sync-api, tx-api} ==0.0.5
     , network >=3.1 && <4
     , optparse-applicative ^>=0.17
+    , prettyprinter
     , text ^>=1.2
 
   ghc-options:     -threaded