Invoking Haddock¶
Haddock is invoked from the command line, like so:
haddock [option ...] file ...
Where each file
is a filename containing a Haskell source module (.hs)
or a Literate Haskell source module (.lhs) or just a module name.
All the modules specified on the command line will be processed together. When one module refers to an entity in another module being processed, the documentation will link directly to that entity.
Entities that cannot be found, for example because they are in a module that isn’t being processed as part of the current batch, simply won’t be hyperlinked in the generated documentation. Haddock will emit warnings listing all the identifiers it couldn’t resolve.
The modules should not be mutually recursive, as Haddock don’t like swimming in circles.
Note that while older version would fail on invalid markup, this is considered a bug in the new versions. If you ever get failed parsing message, please report it.
You must also specify an option for the output format. Currently only
the --html
option for HTML, the --hoogle
option for
outputting Hoogle data, and the --latex
option are functional.
The packaging tool Cabal has Haddock support, and is often used instead of invoking Haddock directly.
The following options are available:
- -B <dir>¶
Tell GHC that its lib directory is dir. Can be used to override the default path.
- -i <file>¶
- --read-interface=<file>¶
- -i <docpath>,<file>
- --read-interface=<docpath>,<file>
- -i <docpath>,<srcpath>,<file>
- --read-interface=<docpath>,<srcpath>,<file>
- -i <docpath>,<srcpath>,<visibility>,<file>
Read the interface file in file, which must have been produced by running Haddock with the
--dump-interface
option. The interface describes a set of modules whose HTML documentation is located in docpath (which may be a relative pathname). The docpath is optional, and defaults to “.”. The srcpath is optional but has no default value.This option allows Haddock to produce separate sets of documentation with hyperlinks between them. The docpath is used to direct hyperlinks to point to the right files; so make sure you don’t move the HTML files later or these links will break. Using a relative docpath means that a documentation subtree can still be moved around without breaking links.
Similarly to docpath, srcpath is used generate cross-package hyperlinks but within sources rendered with
--hyperlinked-source
option.If visibility is set to hidden, modules from that interface file will not be listed in haddock generated content file.
Multiple
--read-interface
options may be given.
- -D <file>¶
- --dump-interface=<file>¶
Produce an interface file [1] in the file file. An interface file contains information Haddock needs to produce more documentation that refers to the modules currently being processed - see the
--read-interface
option for more details. The interface file is in a binary format; don’t try to read it.
- --show-interface=<file>¶
Dumps a binary interface file to stdout in a human readable fashion. Uses json as output format.
- --html, -h¶
Generate documentation in HTML format. Several files will be generated into the current directory (or the specified directory if the
-o
option is given), including the following:module.html
;mini_module.html
An HTML page for each module, and a “mini” page for each used when viewing their synopsis.
index.html
The top level page of the documentation: lists the modules available, using indentation to represent the hierarchy if the modules are hierarchical.
doc-index.html
;doc-index-X.html
The alphabetic index, possibly split into multiple pages if big enough.
some.css
;etc...
Files needed for the themes used. Specify your themes using the
--theme
option.haddock-util.js
Some JavaScript utilities used to implement some of the dynamic features like collapsible sections.
- --mathjax¶
Specify a custom URL for a mathjax-compatible JS script. By default, this is set to MathJax.
- --latex¶
Generate documentation in LaTeX format. Several files will be generated into the current directory (or the specified directory if the
-o
option is given), including the following:package.tex
The top-level LaTeX source file; to format the documentation into PDF you might run something like this:
$ pdflatex package.tex
haddock.sty
The default style. The file contains definitions for various macros used in the LaTeX sources generated by Haddock; to change the way the formatted output looks, you might want to override these by specifying your own style with the
--latex-style
option.module.tex
The LaTeX documentation for each module.
- --latex-style=<style>¶
This option lets you override the default style used by the LaTeX generated by the
--latex
option. Normally Haddock puts a standardhaddock.sty
in the output directory, and includes the command\usepackage{haddock}
in the LaTeX source. If this option is given, thenhaddock.sty
is not generated, and the command is instead\usepackage{style}
.
- --hoogle¶
Generate an index file for the Hoogle search engine. One text file will be generated into the current directory (or the specified directory if the
-o
is given). Note that the--package-name
is required.Since the output is intended to be parsed by Hoogle, some conventions need to be upheld:
Every entity should span exactly one line.
newtype ReaderT r (m :: * -> *) a :: * -> (* -> *) -> * -> *
The one exception to this rule is classes. The body of a class is split up with one class member per line, an opening brace on the line of the header, and a closing brace on a new line after the class.
class Foo a where { foo :: a -> a -> Baz a; type family Baz a; type Baz a = [(a, a)]; }
Entites that are exported only indirectly (for instance data constructors visible via a
ReaderT(..)
export) have their names wrapped in square brackets.[ReaderT] :: (r -> m a) -> ReaderT r m a [runReaderT] :: ReaderT r m a -> r -> m a
- --hyperlinked-source¶
Generate hyperlinked source code (as HTML web page). All rendered files will be put into
src/
subfolder of output directory.Usually, this should be used in combination with
--html
option - generated documentation will then contain references to appropriate code fragments. Previously, this behaviour could be achieved by generating sources using external tool and specifying--source-base
,--source-module
,--source-entity
and related options. Note that these flags are ignored once--hyperlinked-source
is set.In order to make cross-package source hyperlinking possible, appropriate source paths have to be set up when providing interface files using
--read-interface
option.
- --source-css=<style>¶
Use custom CSS file for sources rendered by the
--hyperlinked-source
option. If no custom style file is provided, Haddock will use default one.
- -S, --docbook¶
Reserved for future use (output documentation in DocBook XML format).
- --base-url=<url>¶
Base url for static assets (eg. css, javascript, json files etc.). When present, static assets are not copied. This option is useful when creating documentation for multiple packages, it allows to have a single copy of static assets served from the given url.
- --source-base=<url>¶
- --source-module=<url>¶
- --source-entity=<url>¶
- --source-entity-line=<url>¶
Include links to the source files in the generated documentation. Use the
--source-base
option to add a source code link in the header bar of the contents and index pages. Use the--source-module
to add a source code link in the header bar of each module page. Use the--source-entity
option to add a source code link next to the documentation for every value and type in each module.--source-entity-line
is a flag that gets used for entities that need to link to an exact source location rather than a name, eg. since they were defined inside a Template Haskell splice.In each case URL is the base URL where the source files can be found. For the per-module and per-entity URLs, the following substitutions are made within the string URL:
The string
%M
or%{MODULE}
is replaced by the module name. Note that for the per-entity URLs this is the name of the exporting module.The string
%N
or%{NAME}
is replaced by the name of the exported value or type. This is only valid for the--source-entity
option.The string
%K
or%{KIND}
is replaced by a flag indicating whether the exported name is a valuev
or a typet
. This is only valid for the--source-entity
option.The string
%L
or%{LINE}
is replaced by the number of the line where the exported value or type is defined. This is only valid for the--source-entity
option.The string
%%
is replaced by%
.
If you have html versions of your sources online with anchors for each type and function name, you would say
haddock --source-base=url/ --source-module=url/%M.html --source-entity=url/%M.html#%N
For the
%{MODULE}
substitution you may want to replace the.
character in the module names with some other character (some web servers are known to get confused by multiple.
characters in a file name). To replace it with a character c use%{MODULE/./c}
.One example of a tool that can generate syntax-highlighted HTML from your source code, complete with anchors suitable for use from haddock, is hscolour.
- -s <url>¶
- --source=<url>¶
Deprecated aliases for
--source-module
- --comments-base=<url>¶
- --comments-module=<url>¶
- --comments-entity=<url>¶
documentation. This feature would typically be used in conjunction with a Wiki system.
Use the
--comments-base
option to add a user comments link in the header bar of the contents and index pages. Use the--comments-module
to add a user comments link in the header bar of each module page. Use the--comments-entity
option to add a comments link next to the documentation for every value and type in each module.In each case URL is the base URL where the corresponding comments page can be found. For the per-module and per-entity URLs the same substitutions are made as with the
--source-module
and--source-entity
options above.For example, if you want to link the contents page to a wiki page, and every module to subpages, you would say
haddock --comments-base=url --comments-module=url/%M
If your Wiki system doesn’t like the
.
character in Haskell module names, you can replace it with a different character. For example to replace the.
characters with_
usehaddock --comments-base=url --comments-module=url/%{MODULE/./_}
. Similarly, you can replace the/
in a file name (may be useful for entity comments, but probably not).
- --theme=<path>¶
Specify a theme to be used for HTML (
--html
) documentation. If given multiple times then the pages will use the first theme given by default, and have alternate style sheets for the others. The reader can switch between themes with browsers that support alternate style sheets, or with the “Style” menu that gets added when the page is loaded. If no themes are specified, then just the default built-in theme (“Linuwial”) is used.The path parameter can be one of:
A directory: The base name of the directory becomes the name of the theme. The directory must contain exactly one
some.css
file. Other files, usually image files, will be copied, along with thesome.css
file, into the generated output directory.A CSS file: The base name of the file becomes the name of the theme.
The name of a built-in theme (“Linuwial”, “Ocean”, or “Classic”).
- --built-in-themes¶
Includes the built-in themes (“Linuwial”, “Ocean”, and “Classic”). Can be combined with
--theme
. Note that order matters: The first specified theme will be the default.
- --use-unicode¶
Enable use of Unicode characters in HTML output.
- -p <file>¶
- --prologue=<file>¶
Specify a file containing documentation which is placed on the main contents page under the heading “Description”. The file is parsed as a normal Haddock doc comment (but the comment markers are not required).
- -t <title>¶
- --title=<title>¶
Use title as the page heading for each page in the documentation.This will normally be the name of the library being documented.
The title should be a plain string (no markup please!).
- --package-name=<name>¶
Specify the name of the package being documented.
- --package-version=<version>¶
Specify the version of the package being documented.
- -q <mode>¶
- --qual=<mode>¶
Specify how identifiers are qualified.
mode should be one of
none
(default): don’t qualify any identifiersfull
: always qualify identifiers completelylocal
: only qualify identifiers that are not part of the modulerelative
: like local, but strip name of the module from qualifications of identifiers in submodules
Example: If you generate documentation for module A, then the identifiers A.x, A.B.y and C.z are qualified as follows.
none: x, y, z
full: A.x, A.B.y, C.z
local: x, A.B.y, C.z
relative: x, B.y, C.z
- --since-qual=<mode>¶
Specify how
@since
annotations are qualified.mode should be one of
always
(default): always qualify@since
annotations with a package name and versiononly-external
: only qualify@since
annotations with a package name and version when they do not come from the current package
- --ghc-version¶
Output the version of GHC which Haddock expects to find at :option:-B and exit.
- --print-ghc-path¶
Output the path to the GHC (which Haddock computes based on :option:-B) and exit.
- --print-ghc-libdir¶
Output the path to the GHC
lib
directory (which Haddock computes based on :option:-B) and exit.
- -v¶
- --verbose¶
Increase verbosity. Currently this will cause Haddock to emit some extra warnings, in particular about modules which were imported but it had no information about (this is often quite normal; for example when there is no information about the
Prelude
).
- --use-contents=<url>¶
- --use-index=<url>¶
When generating HTML, do not generate an index. Instead, redirect the Contents and/or Index link on each page to URL. This option is intended for use in conjunction with
--gen-contents
and/or--gen-index
for generating a separate contents and/or index covering multiple libraries.
- --gen-contents¶
- --gen-index¶
Generate an HTML contents and/or index containing entries pulled from all the specified interfaces (interfaces are specified using
-i
or--read-interface
). This is used to generate a single contents and/or index for multiple sets of Haddock documentation.
- --hide <module>¶
Causes Haddock to behave as if module module has the
hide
attribute. (Module Attributes).
- --show <module>¶
Causes Haddock to behave as if module module does not have the
hide
attribute. (Module Attributes).
- --show-all¶
Causes Haddock to behave as if no modules have the
hide
attribute. (Module Attributes).
- --show-extensions <module>¶
Causes Haddock to behave as if module module has the
show-extensions
attribute. (Module Attributes).
- --optghc=<option>¶
Pass option to GHC. Note that there is a double dash there, unlike for GHC.
- --interface-version¶
Prints out the version of the binary Haddock interface files that this version of Haddock generates.
- --compatible-interface-versions¶
Prints out space-separated versions of binary Haddock interface files that this version of Haddock is compatible with.
- --bypass-interface-version-check¶
DANGEROUS Causes Haddock to ignore the interface versions of binary Haddock interface files. This can make Haddock crash during deserialization of interface files.
- --no-tmp-comp-dir¶
Do not use a temporary directory for reading and writing compilation output files (
.o
,.hi
, and stub files). Instead, use the present directory or another directory that you have explicitly told GHC to use via the--optghc
flag.This flag can be used to avoid recompilation if compilation files already exist. Compilation files are produced when Haddock has to process modules that make use of Template Haskell, in which case Haddock compiles the modules using the GHC API.
- --print-missing-docs¶
Print extra information about any undocumented entities.
- --trace-args¶
Make Haddock print the arguments it receives to standard output. This is useful for examining arguments when invoking through
cabal haddock
, ascabal
uses temporary response files to pass arguments to Haddock.
- --no-compilation¶
Always avoids recompilation, only loads the required
.hi
and.hie
files. Haddock will throw an error when it can’t find them. This will not check if the input files are out of date. (This flag implies--no-tmp-comp-dir
.)
- --incremental=<module>¶
Use Haddock in incremental mode. Haddock will generate documentation for the given module only.
Using literate or pre-processed source¶
Since Haddock uses GHC internally, both plain and literate Haskell
sources are accepted without the need for the user to do anything. To
use the C pre-processor, however, the user must pass the -cpp
option to GHC using --optghc
.
Avoiding recompilation¶
With the advent of “hi-haddock”, Haddock now produces documentation from .hi
(Haskell interface) files and .hie
(.hi
extended) files [2], rather
than typechecked module results. This means that as long as the necessary
.hi
and .hie
files are available (i.e. produced by your build process),
recompilation can be avoided during documentation generation.
Note that .hie
files are only necessary to build documentation which
includes hyperlinked source files like this one,
while .hi
files are required for all Haddock documentation flavors.
The first step is to ensure that your build process is producing .hi
files
that contain Haddock docstrings. This requires that you somehow provide the
-fwrite-interface
and -haddock
flags to GHC. If you intend to generate
documentation that includes hyperlinked source files, you should also provide
the -fwrite-ide-info
flag to GHC. You may specify the directory in which GHC
should write the .hi
and .hie
files by providing the
-hidir=/path/to/hidir
and -hiedir=/path/to/hiedir
flags to GHC. If you
are building your application with cabal build
, the default location is in
dist-newstyle/build/<arch>-<os>/ghc-<ghc-version>/<component>-0.1.0/build
.
The next step is to make sure Haddock runs in no-compilation mode by using
the --no-compilation
flag. In addition, Cabal passes a
temporary directory as -hidir
to Haddock by default. This will cause
cabal haddock
to error, since it will never find the necessary
interface files in that temporary directory. To remedy this, pass a
--optghc="-hidir=/path/to/hidir"
flag to Haddock, where /path/to/hidir
is the path to the directory in which your build process is writing .hi
files. You can do this by invoking cabal haddock
with
--haddock-options="--no-compilation --optghc=-hidir --optghc=/path/to/hidir"
.
Following the steps above will allow you to take full advantage of “hi-haddock” and generate Haddock documentation from existing build results without requiring any further compilation.
Incremental mode¶
In incremental mode Haddock generates documentation for only one module, making it possible to generate documentation incrementally. It is useful when working on the documentation, and especially in big packages, since your changes get rendered quickly. Incremental mode takes full advantage of “hi-haddock”: the compiler is never invoked so it’s guaranteed that no recompilation will occur.
There are two major downsides to this method:
The procedure to get links between modules in incremental mode is the same as for links between packages in normal mode, using
--dump-interface
and--read-interface
. So for each dependency you will have to pass the location of the.haddock
file with--read-interface
. It is therefore recommended to use incremental mode in conjunction with a build system like Bazel or Buck to track build dependencies at file level.Class instances from other modules than where the class is defined are not available in incremental mode. This is because the module where the class is defined has to be rendered before the module with the instance, since that module depends on the former. So it is recommended to do a final pass in normal mode before publishing the documentation to f.e. Hackage.