Distribution.Superdoc.Hooks

This module defines Superdoc's parameters, as well as the Cabal user hooks that do Superdoc's "real" work. For an explanation of what that work is, see here: Distribution.Superdoc.

Further, this module exposes some low-level functions that are not exposed in Distribution.Superdoc, but that may be useful for some specialized applications.

Superdoc parameters

data SuperdocArgs

A data structure to hold Superdoc's parameters. Additional parameters may be added in the future, so to ensure forward compatibility, packages should always specify parameters by modifying defaultSuperdocArgs, for example like this:

let params = defaultSuperdocArgs { imageSource = ... }

Constructors

SuperdocArgs

Fields

• imageSource :: ImageSource

  Where to look for image files.

• imageMissing :: ImageMissing

  What to do about missing image files.

• bootstrap :: Bool

  Bootstrapping mode. Required to generate Superdoc's own documentation, because at that point, Superdoc is typically not yet installed. Other packages using Superdoc should not set this flag.

Instances

Eq SuperdocArgs

Methods

(==) :: SuperdocArgs -> SuperdocArgs -> Bool

(/=) :: SuperdocArgs -> SuperdocArgs -> Bool

Show SuperdocArgs

Methods

showsPrec :: Int -> SuperdocArgs -> ShowS

show :: SuperdocArgs -> String

showList :: [SuperdocArgs] -> ShowS

defaultSuperdocArgs :: SuperdocArgs

The default Superdoc parameters.

data ImageSource

This parameter specifies where to find image files that are linked to in the documentation.

Constructors

CopyFrom FilePath

Copy image files from the specified source directory, which is relative to the package root. The default is "images". Superdoc will copy the required images to their appropriate location within the generated HTML documentation. The image files should also be declared as extra-source-files in the .cabal file.

ExtraHtmlFiles

Assume the images are already present in the directory where the Haddock documentation is being generated. This is useful if the images have been declared as extra-html-files in the .cabal file. They will then have been copied to their rightful location by Cabal. Superdoc will check that the required images are present.

Instances

Eq ImageSource

Methods

(==) :: ImageSource -> ImageSource -> Bool

(/=) :: ImageSource -> ImageSource -> Bool

Show ImageSource

Methods

showsPrec :: Int -> ImageSource -> ShowS

show :: ImageSource -> String

showList :: [ImageSource] -> ShowS

data ImageMissing

This parameter specifies what to do when the documentation links to an image that does not exist.

Constructors

FailOnMissing

This is the default setting. Cabal will fail with an error message if the documentation links to an image that does not exist or cannot be found.

IgnoreMissing

Ignore missing image files. Superdoc will still generate HTML image tags, but will not fail if a corresponding image file does not exist. This setting may be useful for testing, or to build documentation when the image files are incomplete or missing. It is not recommended to use this setting for production purposes.

Instances

Eq ImageMissing

Methods

(==) :: ImageMissing -> ImageMissing -> Bool

(/=) :: ImageMissing -> ImageMissing -> Bool

Show ImageMissing

Methods

showsPrec :: Int -> ImageMissing -> ShowS

show :: ImageMissing -> String

showList :: [ImageMissing] -> ShowS

Hooks for the setup program

A hook for Haddock

haddockhook :: SuperdocArgs -> PackageDescription -> LocalBuildInfo -> UserHooks -> HaddockFlags -> IO ()

A hook for Haddock. This simply adds a command line option to the subordinate Haddock process, instructing it to use the superdoc-armor preprocessor. Its purpose is to replace UTF8-encoded Unicode characters by their ASCII armor.

A post-Haddock hook

posthaddock :: SuperdocArgs -> Args -> HaddockFlags -> PackageDescription -> LocalBuildInfo -> IO ()

A hook to run after Haddock completes. This resolves Superdoc markup and ASCII armor in all generated HTML files. It also copies all of the linked images to the HTML directory (depending on the imageSource and imageMissing parameters). Finally, it checks for the "--hyperlink-source" option, and if necessary, calls the posthscolour hook as well (because it is not run from inside Cabal in this situation).

The first argument hold the Superdoc parameters, and the remaining arguments are as for any postHaddock hook.

do_posthaddock :: SuperdocArgs -> FilePath -> IO ()

Do the actual work of the posthaddock hook, given a path to the documentation directory.

handle_images :: ImageSource -> ImageMissing -> Set FilePath -> FilePath -> IO ()

Perform the action described by ImageSource and ImageMissing, for the given set of images. The last argument is the path for the documentation directory.

A post-HsColour hook

posthscolour :: SuperdocArgs -> Args -> HscolourFlags -> PackageDescription -> LocalBuildInfo -> IO ()

A hook to run after HsColour completes. This goes through the files generated by HsColour and replaces UTF8 characters by their corresponding HTML escapes.

do_posthscolour :: FilePath -> IO ()

Do the actual work of the posthaddock hook, given a path to the documentation directory.