Generate and render Ronn documentation.

Ronn is a markdown-like format for describing man-pages. Files written in Ronn can be viewed as markdown (e.g. rendered on GitHub), or converted to Roff or HTML using the ronn command-line.

There are many ways to author or produce man-pages in Roff and HTML formats from a single source, but Ronn produces by far the highest-quality outputs from the simplest source. Tools like man2html or even Pandoc often produce sub-standard output in certain cases, or lack features such as cross-references.

• ronn: document types and rendering function
• ronn-envparse: Env.Parser -> Ronn
• ronn-opt-env-conf: OptEnvConf.Parser -> Ronn
• ronn-optparse-applicative: Options.Applicative.Parser -> Ronn

1. Import the Ronn module for the parsing library or libraries you use

   import Ronn (Ronn(..), ManRef(..), ManSection(..), ronnToText)
   import Ronn.Options.Applicative () -- HasSections instance only

2. Use our helpers to produce a Ronn from a Parser:

   docs :: Parser a -> Ronn
   docs p = Ronn
    { name = ManRef "my-tool" ManSection1
    , description = ["My tool"]
    , sections = getSections "my-tool" $ getSections p
    }

3. Update your main with a hidden argument that uses this function on your actual parser:

    main :: IO ()
    main = do
   +  getArgs >>= \case
   +    ["render-docs"] -> do
   +      T.putStrLn $ ronnToText $ docs optionsParser
   +      exitSuccess
   +    _ -> pure ()
   +
      options <- parseOptions optionsParser
      run options

For example Ronn produced by these packages, see here. You can use the ronn-ng gem produce a high-quality man-page and HTML from this source:

% ronn --style toc --roff --html doc/*.ronn

You can view the HTML produced by this process here.

The following, when present in your parsers, are not tested and may not generate the correct Ronn content. Patches welcome.

• Commands
• Complex <|>-combinations
• many/ some