From 91d530878385a8491671d4fe21cce2a5b0510551 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 7 Jun 2024 14:25:52 -0700 Subject: [PATCH] ;tools: Shake cmdhelp -> cmddocs, now runs hledger to update flag docs Now, updating a command's docs (for hledger manual and for --help) requires running the command (with stack exec -- hledger). The sequence is now a bit recursive: 1. Run hledger CMD -h to update CMD.md with the latest cmdargs help output for CMD's flags. CMD.md is included in the hledger manual, when rendering that. 2. Convert CMD.md to CMD.txt, with pandoc. 3. Build hledger, embedding CMD.txt for cmdargs to use as -h output. This need only be done after changing command docs or flags, and hopefully won't be a hassle. Shake cmddocs now shows progress output to make things clearer. --- Justfile | 2 +- Shake.hs | 53 ++++++++++++++++++++++---- doc/RELEASING.md | 6 +-- hledger/Hledger/Cli/Commands/README.md | 2 +- hledger/hledger.m4.md | 2 +- 5 files changed, 52 insertions(+), 13 deletions(-) diff --git a/Justfile b/Justfile index bdcf82879..02fc03aa9 100644 --- a/Justfile +++ b/Justfile @@ -1096,7 +1096,7 @@ relprep VER: echo "Bumping all version strings to {{ VER }} ..." ./Shake setversion {{ VER }} $COMMIT echo "Updating all command help texts for embedding..." - ./Shake cmdhelp $COMMIT + ./Shake cmddocs $COMMIT echo "Updating all dates in man pages..." ./Shake mandates echo "Generating all the manuals in all formats...." diff --git a/Shake.hs b/Shake.hs index 0c0568efc..0e5175802 100755 --- a/Shake.hs +++ b/Shake.hs @@ -50,6 +50,7 @@ import "safe" Safe import "shake" Development.Shake import "shake" Development.Shake.FilePath import "time" Data.Time +-- import Debug.Trace -- import "hledger-lib" Hledger.Utils.Debug usage = @@ -65,7 +66,10 @@ usage = ,"./Shake setversion [VER] [PKGS] [-c]" ," update versions in source files to */.version or VER" ," and update */*.cabal files" - ,"./Shake cmdhelp [-c] update hledger CLI commands' help texts" + -- ,"./Shake flagdocs [-c] update flags in hledger CLI command docs + -- ," (run after changing command flags)" + ,"./Shake cmddocs [-c] update hledger CLI command help and docs" + ," (run after changing command flags or docs)" ,"./Shake mandates update the date shown in some manual formats" ,"./Shake manuals [-c] update all packages' txt/man/info/web manuals" -- ,"./Shake webmanuals update just the web manuals" @@ -141,9 +145,11 @@ main = do -- hledger manual also includes the markdown files from here: let commandsdir = "hledger/Hledger/Cli/Commands" commandmds <- - filter (not . ("README." `isPrefixOf`) . takeFileName) . filter (".md" `isSuffixOf`) . map (commandsdir ) + sort . filter (not . ("README." `isPrefixOf`) . takeFileName) . filter (".md" `isSuffixOf`) . map (commandsdir ) <$> S.getDirectoryContents commandsdir - let commandtxts = map (-<.> "txt") commandmds + let + commandmdsnew = map (<.> "new") commandmds + commandtxts = map (-<.> "txt") commandmds -- Run the shake rule selected by the first command line argument. -- Other arguments and some custom flags are set aside for the rule @@ -585,14 +591,47 @@ main = do | pkg <- pkgs ] - -- regenerate Hledger/Cli/Commands/*.txt from the .md source files for CLI help - phony "cmdhelp" $ do + -- Update each Hledger/Cli/Commands/*.md, replacing the flags block with latest --help output, + -- or a placeholder if there are no command-specific flags. + -- For hledger manual and also for cmddocs below. + phony "flagdocs" $ do + need commandmdsnew + when commit $ commitIfChanged ";doc: update command flag docs" commandmds + + -- hledger/Hledger/Cli/Commands/CMD.md.new: updates the command-specific flags help + -- within hledger/Hledger/Cli/Commands/CMD.md. Runs "stack exec -- hledger CMD -h". + phonys $ \out -> + if not $ ".md.new" `isSuffixOf` out + then Nothing + else Just $ do + let src = dropExtension out + need [src] + liftIO $ putStrLn ("running hledger, updating flags in " <> src) + srcls <- fmap lines $ liftIO $ readFileStrictly src + let + (pre,rest) = break (=="```flags") srcls + (_,post) = span (/="```") rest + let cmdname = map toLower $ takeBaseName src + cmdhelp <- lines . fromStdout <$> (cmd Shell $ "stack exec -- hledger -h " <> cmdname :: Action (Stdout String)) + let + cmdflagshelp = takeWhile (not.null) $ dropWhile (/="Flags:") cmdhelp + cmdflagshelp' + | null cmdflagshelp = ["Flags:","no command-specific flags"] + | otherwise = cmdflagshelp + liftIO $ writeFile src $ unlines $ concat [pre, ["```flags"], cmdflagshelp', post] + + -- Regenerate Hledger/Cli/Commands/*.txt, rendering the corresponding .md files as plain text. + -- Also updates cmddocs first. + -- For commands' --help output. + phony "cmddocs" $ do need commandtxts when commit $ commitIfChanged ";doc: update help" commandtxts commandtxts |%> \out -> do let src = out -<.> "md" - need [src] + liftIO $ putStrLn ("generating " <> out) + need [src <.> "new"] -- 1. update flags doc in src + need [src] -- 2. depend on src cmd Shell pandoc fromsrcmd src "--lua-filter" "tools/pandoc-dedent-code-blocks.lua" "-t plain" ">" out @@ -730,7 +769,7 @@ main = do -- Update all program-specific docs, eg after setversion. phony "docs" $ need [ - "cmdhelp" + "cmddocs" ,"manuals" ,"changelogs" ] diff --git a/doc/RELEASING.md b/doc/RELEASING.md index 98735be73..e3abfe124 100644 --- a/doc/RELEASING.md +++ b/doc/RELEASING.md @@ -311,8 +311,8 @@ Here's more detail of various steps. - if there are changes, `./Shake cabalfiles -c` #### Up-to-date help -- `./Shake cmdhelp` -- if there are changes, `./Shake cmdhelp -c` +- `./Shake cmddocs` +- if there are changes, `./Shake cmddocs -c` #### Up-to-date manuals - `./Shake mandates` @@ -518,7 +518,7 @@ In release branch, update #### Bump master to next version (major release) - `./Shake setversion MA.JOR.99 -c` -- `./Shake cmdhelp [-c]` (might be empty) +- `./Shake cmddocs [-c]` (might be empty) - `./Shake mandates` - `./Shake manuals -c` diff --git a/hledger/Hledger/Cli/Commands/README.md b/hledger/Hledger/Cli/Commands/README.md index 8da520dd6..bbd9eb6a2 100644 --- a/hledger/Hledger/Cli/Commands/README.md +++ b/hledger/Hledger/Cli/Commands/README.md @@ -11,7 +11,7 @@ After changing md files, regenerating and committing the txt files is optional. If you don't do it, it will get done later (before release). It can be done by: - ./Shake cmdhelp + ./Shake cmddocs Or, by you can regenerate them while also building packages: diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 651b4cf41..4ebbe987a 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -6580,7 +6580,7 @@ See [hledger and Ledger](ledger.md) for full details. m4_dnl Some common markdown links. m4_dnl These are also usable in hledger/Hledger/Cli/Commands/*.md. -m4_dnl Some are defined there also - don't remove, they are needed there for Shake cmdhelp eg. +m4_dnl Some are defined there also - don't remove, they are needed there for Shake cmddocs eg. m4_dnl Duplicate definitions won't give warnings as long as the target is identical. m4_dnl Be wary of pandoc/mdbook handling [shortcut] link syntax differently ?