superdoc-0.1.2.7: Additional documentation markup and Unicode support

Distribution.Superdoc.Hooks

Description

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.

Synopsis

# Superdoc parameters

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 FieldsimageSource :: ImageSourceWhere to look for image files.imageMissing :: ImageMissingWhat to do about missing image files.bootstrap :: BoolBootstrapping 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

 Source # Methods Source # MethodsshowList :: [SuperdocArgs] -> ShowS #

The default Superdoc parameters.

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

 Source # Methods Source # MethodsshowList :: [ImageSource] -> ShowS #

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

 Source # Methods Source # MethodsshowList :: [ImageMissing] -> ShowS #

# Hooks for the setup program

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

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.

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

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 the actual work of the posthaddock hook, given a path to the documentation directory.

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 () Source #

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 the actual work of the posthaddock hook, given a path to the documentation directory.