From bfd47453c76c7fb849c50eed750f61e28dc5cbdb Mon Sep 17 00:00:00 2001 From: Ben Gamari Date: Sun, 7 Feb 2016 11:21:42 -0500 Subject: doc: Switch to Sphinx --- doc/.gitignore | 1 + doc/Makefile | 10 +- doc/README.md | 23 +- doc/aclocal.m4 | 174 ---- doc/conf.py | 69 ++ doc/config.mk.in | 15 - doc/configure.ac | 12 - doc/docbook-xml.mk | 130 --- doc/fptools.css | 36 - doc/ghc.mk | 9 +- doc/haddock.xml | 2329 ---------------------------------------------------- doc/index.rst | 21 + doc/intro.rst | 164 ++++ doc/invoking.rst | 454 ++++++++++ doc/markup.rst | 887 ++++++++++++++++++++ 15 files changed, 1613 insertions(+), 2721 deletions(-) create mode 100644 doc/.gitignore delete mode 100644 doc/aclocal.m4 create mode 100644 doc/conf.py delete mode 100644 doc/config.mk.in delete mode 100644 doc/configure.ac delete mode 100644 doc/docbook-xml.mk delete mode 100644 doc/fptools.css delete mode 100644 doc/haddock.xml create mode 100644 doc/index.rst create mode 100644 doc/intro.rst create mode 100644 doc/invoking.rst create mode 100644 doc/markup.rst (limited to 'doc') diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 00000000..1bf230d1 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +.build-html \ No newline at end of file diff --git a/doc/Makefile b/doc/Makefile index 5f88b708..f4356f43 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,6 +1,8 @@ -include config.mk +SPHINX_BUILD ?= sphinx-build -XML_DOC = haddock -INSTALL_XML_DOC = haddock +all : html -include docbook-xml.mk +.PHONY : html + +html : + $(SPHINX_BUILD) -b html . .build-html diff --git a/doc/README.md b/doc/README.md index cf1fc31b..947d7f93 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,25 +1,10 @@ # Haddock documentation -The documentation is in DocBook XML format. You need some tools to -process it: at least xsltproc, and the DocBook XML DTD and XSL -stylesheets. There's a configure script to detect the right way to -process the documentation on your system, and a Makefile to actually -do the processing (so, on Windows, you'll need Cygwin or MSys in -addition to the DocBook XML tools). To build the HTML documentation: +The documentation is in ReStructuredText format. You need +[Sphinx](http://www.sphinx-doc.org/) to process it. To build the HTML +documentation, - $ autoconf - $ ./configure $ make html -which leaves the HTML documentation in a haddock/ subdirectory. +which leaves the HTML documentation the `.build-html/` subdirectory. -Printable documentation can also be produced, eg.: - - $ make pdf - -or - - $ make ps - -Generating the printed formats requires more tools (fop or xmltex) and -tends to be a bit harder. diff --git a/doc/aclocal.m4 b/doc/aclocal.m4 deleted file mode 100644 index 97ffcb76..00000000 --- a/doc/aclocal.m4 +++ /dev/null @@ -1,174 +0,0 @@ -# FP_GEN_DOCBOOK_XML -# ------------------ -# Generates a DocBook XML V4.2 document in conftest.xml. -AC_DEFUN([FP_GEN_DOCBOOK_XML], -[rm -f conftest.xml -cat > conftest.xml << EOF - - - - A DocBook Test Document - - A Chapter Title - This is a paragraph, referencing . - - - Another Chapter Title - This is another paragraph, referencing . - - -EOF -]) # FP_GEN_DOCBOOK_XML - - -# FP_PROG_XSLTPROC -# ---------------- -# Sets the output variable XsltprocCmd to the full path of the XSLT processor -# xsltproc. XsltprocCmd is empty if xsltproc could not be found. -AC_DEFUN([FP_PROG_XSLTPROC], -[AC_PATH_PROG([XsltprocCmd], [xsltproc]) -if test -z "$XsltprocCmd"; then - AC_MSG_WARN([cannot find xsltproc in your PATH, you will not be able to build the documentation]) -fi -])# FP_PROG_XSLTPROC - - -# FP_DIR_DOCBOOK_XSL(XSL-DIRS) -# ---------------------------- -# Check which of the directories XSL-DIRS contains DocBook XSL stylesheets. The -# output variable DIR_DOCBOOK_XSL will contain the first usable directory or -# will be empty if none could be found. -AC_DEFUN([FP_DIR_DOCBOOK_XSL], -[AC_REQUIRE([FP_PROG_XSLTPROC])dnl -if test -n "$XsltprocCmd"; then - AC_CACHE_CHECK([for DocBook XSL stylesheet directory], fp_cv_dir_docbook_xsl, - [FP_GEN_DOCBOOK_XML - fp_cv_dir_docbook_xsl=no - for fp_var in $1; do - if $XsltprocCmd ${fp_var}/html/docbook.xsl conftest.xml > /dev/null 2>&1; then - fp_cv_dir_docbook_xsl=$fp_var - break - fi - done - rm -rf conftest*]) -fi -if test x"$fp_cv_dir_docbook_xsl" = xno; then - AC_MSG_WARN([cannot find DocBook XSL stylesheets, you will not be able to build the documentation]) - DIR_DOCBOOK_XSL= -else - DIR_DOCBOOK_XSL=$fp_cv_dir_docbook_xsl -fi -AC_SUBST([DIR_DOCBOOK_XSL]) -])# FP_DIR_DOCBOOK_XSL - - -# FP_PROG_XMLLINT -# ---------------- -# Sets the output variable XmllintCmd to the full path of the XSLT processor -# xmllint. XmllintCmd is empty if xmllint could not be found. -AC_DEFUN([FP_PROG_XMLLINT], -[AC_PATH_PROG([XmllintCmd], [xmllint]) -if test -z "$XmllintCmd"; then - AC_MSG_WARN([cannot find xmllint in your PATH, you will not be able to validate your documentation]) -fi -])# FP_PROG_XMLLINT - - -# FP_CHECK_DOCBOOK_DTD -# -------------------- -AC_DEFUN([FP_CHECK_DOCBOOK_DTD], -[AC_REQUIRE([FP_PROG_XMLLINT])dnl -if test -n "$XmllintCmd"; then - AC_MSG_CHECKING([for DocBook DTD]) - FP_GEN_DOCBOOK_XML - if $XmllintCmd --valid --noout conftest.xml > /dev/null 2>&1; then - AC_MSG_RESULT([ok]) - else - AC_MSG_RESULT([failed]) - AC_MSG_WARN([cannot find a DTD for DocBook XML V4.2, you will not be able to validate your documentation]) - AC_MSG_WARN([check your XML_CATALOG_FILES environment variable and/or /etc/xml/catalog]) - fi - rm -rf conftest* -fi -])# FP_CHECK_DOCBOOK_DTD - - -# FP_GEN_FO -# ------------------ -# Generates a formatting objects document in conftest.fo. -AC_DEFUN([FP_GEN_FO], -[rm -f conftest.fo -cat > conftest.fo << EOF - - - - - - - - - - - Test! - - - - -EOF -]) # FP_GEN_FO - - -# FP_PROG_FOP -# ----------- -# Set the output variable 'FopCmd' to the first working 'fop' in the current -# 'PATH'. Note that /usr/bin/fop is broken in SuSE 9.1 (unpatched), so try -# /usr/share/fop/fop.sh in that case (or no 'fop'), too. -AC_DEFUN([FP_PROG_FOP], -[AC_PATH_PROGS([FopCmd1], [fop]) -if test -n "$FopCmd1"; then - AC_CACHE_CHECK([for $FopCmd1 usability], [fp_cv_fop_usability], - [FP_GEN_FO - if "$FopCmd1" -fo conftest.fo -ps conftest.ps > /dev/null 2>&1; then - fp_cv_fop_usability=yes - else - fp_cv_fop_usability=no - fi - rm -rf conftest*]) - if test x"$fp_cv_fop_usability" = xyes; then - FopCmd=$FopCmd1 - fi -fi -if test -z "$FopCmd"; then - AC_PATH_PROGS([FopCmd2], [fop.sh], , [/usr/share/fop]) - FopCmd=$FopCmd2 -fi -AC_SUBST([FopCmd]) -])# FP_PROG_FOP - - -# FP_PROG_FO_PROCESSOR -# -------------------- -# Try to find an FO processor. PassiveTeX output is sometimes a bit strange, so -# try FOP first. Sets the output variables FopCmd, XmltexCmd, DvipsCmd, and -# PdfxmltexCmd. -AC_DEFUN([FP_PROG_FO_PROCESSOR], -[AC_REQUIRE([FP_PROG_FOP]) -AC_PATH_PROG([XmltexCmd], [xmltex]) -AC_PATH_PROG([DvipsCmd], [dvips]) -if test -z "$FopCmd"; then - if test -z "$XmltexCmd"; then - AC_MSG_WARN([cannot find an FO => DVI converter, you will not be able to build DVI or PostScript documentation]) - else - if test -z "$DvipsCmd"; then - AC_MSG_WARN([cannot find a DVI => PS converter, you will not be able to build PostScript documentation]) - fi - fi - AC_PATH_PROG([PdfxmltexCmd], [pdfxmltex]) - if test -z "$PdfxmltexCmd"; then - AC_MSG_WARN([cannot find an FO => PDF converter, you will not be able to build PDF documentation]) - fi -elif test -z "$XmltexCmd"; then - AC_MSG_WARN([cannot find an FO => DVI converter, you will not be able to build DVI documentation]) -fi -])# FP_PROG_FO_PROCESSOR diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 00000000..d6b8bda8 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,69 @@ +# -*- coding: utf-8 -*- + +import sys +import os +import shlex + +extensions = [] + +source_suffix = '.rst' +master_doc = 'index' + +# General information about the project. +project = u'Haddock' +copyright = u'2016, Simon Marlow' +author = u'Simon Marlow' +version = '1.0' +release = '1.0' + +language = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['.build'] +todo_include_todos = False + +# Syntax highlighting +highlight_language = 'haskell' +pygments_style = 'tango' + +# -- Options for HTML output ---------------------------------------------- + +html_theme = 'alabaster' +htmlhelp_basename = 'Haddockdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { } + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'Haddock.tex', u'Haddock Documentation', + u'Simon Marlow', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'haddock', u'Haddock Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'Haddock', u'Haddock Documentation', + author, 'Haddock', 'One line description of project.', + 'Miscellaneous'), +] + diff --git a/doc/config.mk.in b/doc/config.mk.in deleted file mode 100644 index e286794c..00000000 --- a/doc/config.mk.in +++ /dev/null @@ -1,15 +0,0 @@ -#----------------------------------------------------------------------------- -# DocBook XML stuff - -XSLTPROC = @XsltprocCmd@ -XMLLINT = @XmllintCmd@ -FOP = @FopCmd@ -XMLTEX = @XmltexCmd@ -PDFXMLTEX = @PdfxmltexCmd@ -DVIPS = @DvipsCmd@ - -DIR_DOCBOOK_XSL = @DIR_DOCBOOK_XSL@ - -XSLTPROC_LABEL_OPTS = --stringparam toc.section.depth 3 \ - --stringparam section.autolabel 1 \ - --stringparam section.label.includes.component.label 1 diff --git a/doc/configure.ac b/doc/configure.ac deleted file mode 100644 index acf459e8..00000000 --- a/doc/configure.ac +++ /dev/null @@ -1,12 +0,0 @@ - -AC_INIT([Haddock docs], [1.0], [simonmar@microsoft.com], []) - -AC_CONFIG_SRCDIR([Makefile]) - -dnl ** check for DocBook toolchain -FP_CHECK_DOCBOOK_DTD -FP_DIR_DOCBOOK_XSL([/usr/share/xml/docbook/stylesheet/nwalsh/current /usr/share/xml/docbook/stylesheet/nwalsh /usr/share/sgml/docbook/docbook-xsl-stylesheets* /usr/share/sgml/docbook/xsl-stylesheets* /opt/kde?/share/apps/ksgmltools2/docbook/xsl /usr/share/docbook-xsl /usr/share/sgml/docbkxsl /usr/local/share/xsl/docbook /sw/share/xml/xsl/docbook-xsl /usr/share/xml/docbook/xsl-stylesheets-*]) -FP_PROG_FO_PROCESSOR - -AC_CONFIG_FILES([config.mk]) -AC_OUTPUT diff --git a/doc/docbook-xml.mk b/doc/docbook-xml.mk deleted file mode 100644 index f6048187..00000000 --- a/doc/docbook-xml.mk +++ /dev/null @@ -1,130 +0,0 @@ -#----------------------------------------------------------------------------- -# DocBook XML - -.PHONY: html html-no-chunks chm HxS fo dvi ps pdf - -ifneq "$(XML_DOC)" "" - -all :: html - -# multi-file XML document: main document name is specified in $(XML_DOC), -# sub-documents (.xml files) listed in $(XML_SRCS). - -ifeq "$(XML_SRCS)" "" -XML_SRCS = $(wildcard *.xml) -endif - -XML_HTML = $(addsuffix /index.html,$(basename $(XML_DOC))) -XML_HTML_NO_CHUNKS = $(addsuffix .html,$(XML_DOC)) -XML_CHM = $(addsuffix .chm,$(XML_DOC)) -XML_HxS = $(addsuffix .HxS,$(XML_DOC)) -XML_FO = $(addsuffix .fo,$(XML_DOC)) -XML_DVI = $(addsuffix .dvi,$(XML_DOC)) -XML_PS = $(addsuffix .ps,$(XML_DOC)) -XML_PDF = $(addsuffix .pdf,$(XML_DOC)) - -$(XML_HTML) $(XML_NO_CHUNKS_HTML) $(XML_FO) $(XML_DVI) $(XML_PS) $(XML_PDF) :: $(XML_SRCS) - -html :: $(XML_HTML) -html-no-chunks :: $(XML_HTML_NO_CHUNKS) -chm :: $(XML_CHM) -HxS :: $(XML_HxS) -fo :: $(XML_FO) -dvi :: $(XML_DVI) -ps :: $(XML_PS) -pdf :: $(XML_PDF) - -CLEAN_FILES += $(XML_HTML_NO_CHUNKS) $(XML_FO) $(XML_DVI) $(XML_PS) $(XML_PDF) - -FPTOOLS_CSS = fptools.css - -clean :: - $(RM) -rf $(XML_DOC).out $(basename $(XML_DOC)) $(basename $(XML_DOC))-htmlhelp - -validate :: - $(XMLLINT) --valid --noout $(XMLLINT_OPTS) $(XML_DOC).xml -endif - -#----------------------------------------------------------------------------- -# DocBook XML suffix rules -# - -%.html : %.xml - $(XSLTPROC) --output $@ \ - --stringparam html.stylesheet $(FPTOOLS_CSS) \ - $(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \ - $(DIR_DOCBOOK_XSL)/html/docbook.xsl $< - -%/index.html : %.xml - $(RM) -rf $(dir $@) - $(XSLTPROC) --stringparam base.dir $(dir $@) \ - --stringparam use.id.as.filename 1 \ - --stringparam html.stylesheet $(FPTOOLS_CSS) \ - $(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \ - $(DIR_DOCBOOK_XSL)/html/chunk.xsl $< - cp $(FPTOOLS_CSS) $(dir $@) - -# Note: Numeric labeling seems to be uncommon for HTML Help -%-htmlhelp/index.html : %.xml - $(RM) -rf $(dir $@) - $(XSLTPROC) --stringparam base.dir $(dir $@) \ - --stringparam manifest.in.base.dir 1 \ - --stringparam htmlhelp.chm "..\\"$(basename $<).chm \ - $(XSLTPROC_OPTS) \ - $(DIR_DOCBOOK_XSL)/htmlhelp/htmlhelp.xsl $< - -%-htmlhelp2/collection.HxC : %.xml - $(RM) -rf $(dir $@) - $(XSLTPROC) --stringparam base.dir $(dir $@) \ - --stringparam use.id.as.filename 1 \ - --stringparam manifest.in.base.dir 1 \ - $(XSLTPROC_OPTS) \ - $(DIR_DOCBOOK_XSL)/htmlhelp2/htmlhelp2.xsl $< - -# TODO: Detect hhc & Hxcomp via autoconf -# -# Two obstacles here: -# -# * The reason for the strange "if" below is that hhc returns 0 on error and 1 -# on success, the opposite of what shells and make expect. -# -# * There seems to be some trouble with DocBook indices, but the *.chm looks OK, -# anyway, therefore we pacify make by "|| true". Ugly... -# -%.chm : %-htmlhelp/index.html - ( cd $(dir $<) && if hhc htmlhelp.hhp ; then false ; else true ; fi ) || true - -%.HxS : %-htmlhelp2/collection.HxC - ( cd $(dir $<) && if Hxcomp -p collection.HxC -o ../$@ ; then false ; else true ; fi ) - -%.fo : %.xml - $(XSLTPROC) --output $@ \ - --stringparam draft.mode no \ - $(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \ - $(DIR_DOCBOOK_XSL)/fo/docbook.xsl $< - -ifeq "$(FOP)" "" -ifneq "$(PDFXMLTEX)" "" -%.pdf : %.fo - $(PDFXMLTEX) $< - if grep "LaTeX Warning: Label(s) may have changed.Rerun to get cross-references right." $(basename $@).log > /dev/null ; then \ - $(PDFXMLTEX) $< ; \ - $(PDFXMLTEX) $< ; \ - fi -endif -else -%.ps : %.fo - $(FOP) $(FOP_OPTS) -fo $< -ps $@ - -%.pdf : %.fo - $(FOP) $(FOP_OPTS) -fo $< -pdf $@ -endif - -ifneq "$(XMLTEX)" "" -%.dvi : %.fo - $(XMLTEX) $< - if grep "LaTeX Warning: Label(s) may have changed.Rerun to get cross-references right." $(basename $@).log > /dev/null ; then \ - $(XMLTEX) $< ; \ - $(XMLTEX) $< ; \ - fi -endif diff --git a/doc/fptools.css b/doc/fptools.css deleted file mode 100644 index 5c7fc47b..00000000 --- a/doc/fptools.css +++ /dev/null @@ -1,36 +0,0 @@ -div { - font-family: sans-serif; - color: black; - background: white -} - -h1, h2, h3, h4, h5, h6, p.title { color: #005A9C } - -h1 { font: 170% sans-serif } -h2 { font: 140% sans-serif } -h3 { font: 120% sans-serif } -h4 { font: bold 100% sans-serif } -h5 { font: italic 100% sans-serif } -h6 { font: small-caps 100% sans-serif } - -pre { - font-family: monospace; - border-width: 1px; - border-style: solid; - padding: 0.3em -} - -pre.screen { color: #006400 } -pre.programlisting { color: maroon } - -div.example { - background-color: #fffcf5; - margin: 1ex 0em; - border: solid #412e25 1px; - padding: 0ex 0.4em -} - -a:link { color: #0000C8 } -a:hover { background: #FFFFA8 } -a:active { color: #D00000 } -a:visited { color: #680098 } diff --git a/doc/ghc.mk b/doc/ghc.mk index 73d6b7f0..52a2f2a5 100644 --- a/doc/ghc.mk +++ b/doc/ghc.mk @@ -10,6 +10,11 @@ # # ----------------------------------------------------------------------------- -utils/haddock/doc_DOCBOOK_SOURCES = utils/haddock/doc/haddock.xml +INSTALL_HTML_DOC_DIRS += utils/haddock/doc/haddock + +html : html_utils/haddock/doc + +html_utils/haddock/doc : + make -C utils/haddock/doc html SPHINX_BUILD=$(SPHINXBUILD) + cp -R utils/haddock/doc/.build-html utils/haddock/doc/haddock -$(eval $(call docbook,utils/haddock/doc,haddock)) diff --git a/doc/haddock.xml b/doc/haddock.xml deleted file mode 100644 index e805a437..00000000 --- a/doc/haddock.xml +++ /dev/null @@ -1,2329 +0,0 @@ - - - - - - - - -] > - - - - 2015-06-02 - Haddock User Guide - - Simon - Marlow - -
marlowsd@gmail.com
- - David - Waern - -
david.waern@gmail.com
- - Mateusz - Kowalczyk - -
fuuzetsu@fuuzetsu.co.uk
- - 2010 - Simon Marlow, David Waern - - - 2013-2015 - Mateusz Kowalczyk - - - This document describes Haddock version 2.16.2, a Haskell - documentation tool. - - - - - - - - Introduction - - This is Haddock, a tool for automatically generating - documentation from annotated Haskell source code. Haddock was - designed with several goals in mind: - - - - When documenting APIs, it is desirable to keep the - documentation close to the actual interface or implementation - of the API, preferably in the same file, to reduce the risk - that the two become out of sync. Haddock therefore lets you - write the documentation for an entity (function, type, or - class) next to the definition of the entity in the source - code. - - - There is a tremendous amount of useful API documentation - that can be extracted from just the bare source code, - including types of exported functions, definitions of data - types and classes, and so on. Haddock can therefore generate - documentation from a set of straight Haskell 98 modules, and - the documentation will contain precisely the interface that is - available to a programmer using those modules. - - - Documentation annotations in the source code should be - easy on the eye when editing the source code itself, so as not - to obscure the code and to make reading and writing - documentation annotations easy. The easier it is to write - documentation, the more likely the programmer is to do it. - Haddock therefore uses lightweight markup in its annotations, - taking several ideas from IDoc. - In fact, Haddock can understand IDoc-annotated source - code. - - - The documentation should not expose any of the structure - of the implementation, or to put it another way, the - implementer of the API should be free to structure the - implementation however he or she wishes, without exposing any - of that structure to the consumer. In practical terms, this - means that while an API may internally consist of several - Haskell modules, we often only want to expose a single module - to the user of the interface, where this single module just - re-exports the relevant parts of the implementation - modules. - - Haddock therefore understands the Haskell module system - and can generate documentation which hides not only - non-exported entities from the interface, but also the - internal module structure of the interface. A documentation - annotation can still be placed next to the implementation, and - it will be propagated to the external module in the generated - documentation. - - - Being able to move around the documentation by following - hyperlinks is essential. Documentation generated by Haddock - is therefore littered with hyperlinks: every type and class - name is a link to the corresponding definition, and - user-written documentation annotations can contain identifiers - which are linked automatically when the documentation is - generated. - - - We might want documentation in multiple formats - online - and printed, for example. Haddock comes with HTML, LaTeX, - and Hoogle backends, and it is structured in such a way that adding new - backends is straightforward. - - - -
- Obtaining Haddock - - Distributions (source & binary) of Haddock can be obtained - from its web - site. - - Up-to-date sources can also be obtained from our public - darcs repository. The Haddock sources are at - http://code.haskell.org/haddock. See - darcs.net for more - information on the darcs version control utility. -
- -
- License - - The following license covers this documentation, and the - Haddock source code, except where otherwise indicated. - -
- Copyright 2002-2010, Simon Marlow. All rights reserved. - - Redistribution and use in source and binary forms, with - or without modification, are permitted provided that the - following conditions are met: - - - - Redistributions of source code must retain the above - copyright notice, this list of conditions and the - following disclaimer. - - - Redistributions in binary form must reproduce the - above copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other - materials provided with the distribution. - - - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS - IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND - FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT - SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; - OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF - THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY - OF SUCH DAMAGE. -
-
- -
- Contributors - Haddock was originally written by Simon Marlow. Since it is an open source - project, many people have contributed to its development over the years. - Below is a list of contributors in alphabetical order that we hope is - somewhat complete. If you think you are missing from this list, please contact - us. - - - Ashley Yakeley - Benjamin Franksen - Brett Letner - Clemens Fruhwirth - Conal Elliott - David Waern - Duncan Coutts - George Pollard - George Russel - Hal Daume - Ian Lynagh - Isaac Dupree - Joachim Breitner - Krasimir Angelov - Lennart Augustsson - Luke Plant - Malcolm Wallace - Manuel Chakravarty - Mark Lentczner - Mark Shields - Mateusz Kowalczyk - Mike Thomas - Neil Mitchell - Oliver Brown - Roman Cheplyaka - Ross Paterson - Sigbjorn Finne - Simon Hengel - Simon Marlow - Simon Peyton-Jones - Stefan O'Rear - Sven Panne - Thomas Schilling - Wolfgang Jeltsch - Yitzchak Gale - -
-
- Acknowledgements - - Several documentation systems provided the inspiration for - Haddock, most notably: - - - - - IDoc - - - HDoc - - - - Doxygen - - - - and probably several others I've forgotten. - - Thanks to the the members - of haskelldoc@haskell.org, - haddock@projects.haskell.org and everyone who - contributed to the many libraries that Haddock makes use - of. -
- - - - - 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 option for HTML and the - option for outputting Hoogle data are - functional. - - The packaging - tool Cabal - has Haddock support, and is often used instead of invoking Haddock - directly. - - The following options are available: - - - - - - - dir - - - Tell GHC that that its lib directory is - dir. Can be used to override the default path. - - - - - - - dir - - - - =dir - - - Generate files into dir - instead of the current directory. - - - - - - - dir - - - - =dir - - - Use Haddock auxiliary files (themes, javascript, etc...) in dir. - - - - - - - file - - - - docpath,file - - - - docpath,srcpath,file - - - - =file - - - - =docpath,file - - - - =docpath,srcpath,file - - - Read the interface file in - file, which must have been - produced by running Haddock with the - 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 - option. - - Multiple options may - be given. - - - - - - - file - - - - =file - - - Produce an interface - fileHaddock interface files are - not the same as Haskell interface files, I just couldn't - think of a better name. - 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 option - for more details. The interface file is in a binary format; - don't try to read it. - - - - - - - - - - - - - - Generate documentation in HTML format. Several files - will be generated into the current directory (or the - specified directory if the 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 in frames. - - - - 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. - - - - frames.html - - The top level document when viewing in frames. - - - - some.css - etc... - - Files needed for the themes used. Specify your themes - using the option. - - - - haddock-util.js - - Some JavaScript utilities used to implement some of the - dynamic features like collapsible sections, and switching to - frames view. - - - - - - - - - - - - - Generate documentation in LaTeX format. Several files - will be generated into the current directory (or the - specified directory if the 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 option. - - - - module.tex - - The LaTeX documentation for - each module. - - - - - - - - - - - - - This option lets you override the default style used - by the LaTeX generated by the option. - Normally Haddock puts a - standard haddock.sty in the output - directory, and includes the - command \usepackage{haddock} in the - LaTeX source. If this option is given, - then haddock.sty is not generated, - and the command is - instead \usepackage{style}. - - - - - - - - - - - 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 - 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 , - , - and related options. Note that these flags are ignored once - is set. - In order to make cross-package source hyperlinking possible, - appropriate source paths have to be set up when providing - interface files using - option. - - - - - - - - - - Use custom CSS file for sources rendered by the - option. If no custom style - file is provided, Haddock will use default one. - - - - - - - - - - - - - - Reserved for future use (output documentation in DocBook XML - format). - - - - - - - =URL - - - - =URL - - - - =URL - - - - =URL - - - Include links to the source files in the generated - documentation. Use the option to add a - source code link in the header bar of the contents and index pages. - Use the to add a source code link in - the header bar of each module page. Use the - option to add a source code link - next to the documentation for every value and type in each module. - 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 %F or %{FILE} - is replaced by the original source file name. Note that for the - per-entity URLs this is the name of the defining - module. - - - The string %N or %{NAME} - is replaced by the name of the exported value or type. This is - only valid for the option. - - - The string %K or %{KIND} - is replaced by a flag indicating whether the exported name is a value - 'v' or a type 't'. This is - only valid for the 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 - option. - - - The string %% is replaced by - %. - - - - - For example, if your sources are online under some directory, - you would say - haddock --source-base=url/ - --source-module=url/%F - - 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}. - - Similarly, for the %{FILE} substitution - you may want to replace the '/' character in - the file names with some other character (especially for links - to colourised entity source code with a shared css file). To replace - it with a character c use - %{FILE///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. - - - - - - - - URL - - - - =URL - - - Deprecated aliases for - - - - - - - =URL - - - - =URL - - - - =URL - - - Include links to pages where readers may comment on the - documentation. This feature would typically be used in conjunction - with a Wiki system. - - Use the option to add a - user comments link in the header bar of the contents and index pages. - Use the to add a user comments - link in the header bar of each module page. Use the - 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 and - 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 - '_' use haddock - --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.) - - - - - - - - =path - - - Specify a theme to be used for 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 - ("Ocean") 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 - the some.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 - ("Ocean" or "Classic"). - - - - - - - - - - - - Includes the built-in themes ("Ocean" and "Classic"). - Can be combined with . Note that order - matters: The first specified theme will be the default. - - - - - - - file - - - - =file - - - Deprecated aliases for - - - - - - - file - - - - =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). - - - - - - - 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!). - - - - - - - mode - - - - =mode - - - - Specify how identifiers are qualified. - - - mode should be one of - - - none (default): don't qualify any identifiers - - - full: always qualify identifiers completely - - - local: only qualify identifiers that are not part - of the module - - - relative: 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 - - - - - - - - - - - - - - - - - Display help and exit. - - - - - - - - - - - - - - Output version information and exit. - - - - - - - - - - - - - - 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). - - - - - - - - - - - - - - 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 and/or - for - generating a separate contents and/or index covering multiple - libraries. - - - - - - - - - - - - - - Generate an HTML contents and/or index containing entries pulled - from all the specified interfaces (interfaces are specified using - or ). - This is used to generate a single contents and/or index for multiple - sets of Haddock documentation. - - - - - - - - - - - Causes Haddock to behave as if every module has the - ignore-exports attribute (). This might be useful for - generating implementation documentation rather than interface - documentation, for example. - - - - - - - -  module - - - Causes Haddock to behave as if module - module has the hide - attribute. (). - - - - - - - -  module - - - Causes Haddock to behave as if module - module has the show-extensions - attribute. (). - - - - - - - =option - - - Pass option to GHC. Note that there is a double dash there, unlike for GHC. - - - - - - - - - - - - - - Turn off all warnings. - - - - - - - - - - - Prints out space-separated versions of binary Haddock interface files that this version is compatible - with. - - - - - - - - - - - - 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 extra information about any undocumented entities. - - - - - -
- 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 the option to GHC - using . - -
- - - - - Documentation and Markup - - Haddock understands special documentation annotations in the - Haskell source file and propagates these into the generated - documentation. The annotations are purely optional: if there are - no annotations, Haddock will just generate documentation that - contains the type signatures, data type declarations, and class - declarations exported by each of the modules being - processed. - -
- Documenting a top-level declaration - - The simplest example of a documentation annotation is for - documenting any top-level declaration (function type signature, - type declaration, or class declaration). For example, if the - source file contains the following type signature: - - -square :: Int -> Int -square x = x * x - - - Then we can document it like this: - - --- |The 'square' function squares an integer. -square :: Int -> Int -square x = x * x - - - - The -- | syntax begins a - documentation annotation, which applies to the - following declaration in the source file. - Note that the annotation is just a comment in Haskell — it - will be ignored by the Haskell compiler. - - The declaration following a documentation annotation - should be one of the following: - - - A type signature for a top-level function, - - - A data declaration, - - - A newtype declaration, - - - A type declaration - - - A class declaration, - - - A data family or - type family declaration, or - - - A data instance or - type instance declaration. - - - - If the annotation is followed by a different kind of - declaration, it will probably be ignored by Haddock. - - Some people like to write their documentation - after the declaration; this is possible in - Haddock too: - - -square :: Int -> Int --- ^The 'square' function squares an integer. -square x = x * x - - - Note that Haddock doesn't contain a Haskell type system - — if you don't write the type signature for a function, - then Haddock can't tell what its type is and it won't be - included in the documentation. - - Documentation annotations may span several lines; the - annotation continues until the first non-comment line in the - source file. For example: - - --- |The 'square' function squares an integer. --- It takes one argument, of type 'Int'. -square :: Int -> Int -square x = x * x - - - You can also use Haskell's nested-comment style for - documentation annotations, which is sometimes more convenient - when using multi-line comments: - - -{-| - The 'square' function squares an integer. - It takes one argument, of type 'Int'. --} -square :: Int -> Int -square x = x * x - - -
-
- Documenting parts of a declaration - - In addition to documenting the whole declaration, in some - cases we can also document individual parts of the - declaration. - -
- Class methods - - Class methods are documented in the same way as top - level type signatures, by using either the - -- | or - -- ^ - annotations: - - -class C a where - -- | This is the documentation for the 'f' method - f :: a -> Int - -- | This is the documentation for the 'g' method - g :: Int -> a - -
- -
- Constructors and record fields - - Constructors are documented like so: - - -data T a b - -- | This is the documentation for the 'C1' constructor - = C1 a b - -- | This is the documentation for the 'C2' constructor - | C2 a b - - - or like this: - - -data T a b - = C1 a b -- ^ This is the documentation for the 'C1' constructor - | C2 a b -- ^ This is the documentation for the 'C2' constructor - - - Record fields are documented using one of these - styles: - - -data R a b = - C { -- | This is the documentation for the 'a' field - a :: a, - -- | This is the documentation for the 'b' field - b :: b - } - -data R a b = - C { a :: a -- ^ This is the documentation for the 'a' field - , b :: b -- ^ This is the documentation for the 'b' field - } - - - Alternative layout styles are generally accepted by - Haddock - for example doc comments can appear before or after - the comma in separated lists such as the list of record fields - above. - - In case that more than one constructor exports a field - with the same name, the documentation attached to the first - occurence of the field will be used, even if a comment is not - present. - - - -data T a = A { someField :: a -- ^ Doc for someField of A - } - | B { someField :: a -- ^ Doc for someField of B - } - - - In the above example, all occurences of - someField in the documentation are going to - be documented with Doc for someField of A. - Note that Haddock versions 2.14.0 and before would join up - documentation of each field and render the result. The reason - for this seemingly weird behaviour is the fact that - someField is actually the same (partial) - function. - -
- -
- Function arguments - - Individual arguments to a function may be documented - like this: - - -f :: Int -- ^ The 'Int' argument - -> Float -- ^ The 'Float' argument - -> IO () -- ^ The return value - -
-
- -
- The module description - - A module itself may be documented with multiple fields - that can then be displayed by the backend. In particular, the - HTML backend displays all the fields it currently knows - about. We first show the most complete module documentation - example and then talk about the fields. - - -{-| -Module : W -Description : Short description -Copyright : (c) Some Guy, 2013 - Someone Else, 2014 -License : GPL-3 -Maintainer : sample@email.com -Stability : experimental -Portability : POSIX - -Here is a longer description of this module, containing some -commentary with @some markup@. --} -module W where -... - - - The Module field should be clear. It - currently doesn't affect the output of any of the backends but - you might want to include it for human information or for any - other tools that might be parsing these comments without the - help of GHC. - - The Description field accepts some short text - which outlines the general purpose of the module. If you're - generating HTML, it will show up next to the module link in - the module index. - - The Copyright, License, - Maintainer and Stability fields - should be obvious. An alternative spelling for the - License field is accepted as - Licence but the output will always prefer - License. - - The Portability field has seen varied use - by different library authors. Some people put down things like - operating system constraints there while others put down which GHC - extensions are used in the module. Note that you might want to - consider using the show-extensions module flag for the - latter. - - Finally, a module may contain a documentation comment - before the module header, in which case this comment is - interpreted by Haddock as an overall description of the module - itself, and placed in a section entitled - Description in the documentation for the module. - All usual Haddock markup is valid in this comment. - - All fields are optional but they must be in order if they - do appear. Multi-line fields are accepted but the consecutive - lines have to start indented more than their label. If your - label is indented one space as is often the case with - -- syntax, the consecutive lines have to start at - two spaces at the very least. Please note that we do not enforce - the format for any of the fields and the established formats are - just a convention. - -
- -
- Controlling the documentation structure - - Haddock produces interface documentation that lists only - the entities actually exported by the module. The documentation - for a module will include all entities - exported by that module, even if they were re-exported by - another module. The only exception is when Haddock can't see - the declaration for the re-exported entity, perhaps because it - isn't part of the batch of modules currently being - processed. - - However, to Haddock the export list has even more - significance than just specifying the entities to be included in - the documentation. It also specifies the - order that entities will be listed in the - generated documentation. This leaves the programmer free to - implement functions in any order he/she pleases, and indeed in - any module he/she pleases, but still - specify the order that the functions should be documented in the - export list. Indeed, many programmers already do this: the - export list is often used as a kind of ad-hoc interface - documentation, with headings, groups of functions, type - signatures and declarations in comments. - - You can insert headings and sub-headings in the - documentation by including annotations at the appropriate point - in the export list. For example: - - -module Foo ( - -- * Classes - C(..), - -- * Types - -- ** A data type - T, - -- ** A record - R, - -- * Some functions - f, g - ) where - - - Headings are introduced with the syntax - -- *, - -- ** and so on, where - the number of *s indicates the level of the - heading (section, sub-section, sub-sub-section, etc.). - - If you use section headings, then Haddock will generate a - table of contents at the top of the module documentation for - you. - - The alternative style of placing the commas at the - beginning of each line is also supported. eg.: - - -module Foo ( - -- * Classes - , C(..) - -- * Types - -- ** A data type - , T - -- ** A record - , R - -- * Some functions - , f - , g - ) where - - -
- Re-exporting an entire module - - Haskell allows you to re-export the entire contents of a - module (or at least, everything currently in scope that was - imported from a given module) by listing it in the export - list: - - -module A ( - module B, - module C - ) where - - - What will the Haddock-generated documentation for this - module look like? Well, it depends on how the modules - B and C are imported. - If they are imported wholly and without any - hiding qualifiers, then the documentation - will just contain a cross-reference to the documentation for - B and C. However, if - the modules are not completely - re-exported, for example: - - -module A ( - module B, - module C - ) where - -import B hiding (f) -import C (a, b) - - - then Haddock behaves as if the set of entities - re-exported from B and C - had been listed explicitly in the export - listNOTE: this is not fully implemented at the - time of writing (version 0.2). At the moment, Haddock always - inserts a cross-reference. - . - - The exception to this rule is when the re-exported - module is declared with the hide attribute - (), in which case the module - is never cross-referenced; the contents are always expanded in - place in the re-exporting module. -
- -
- Omitting the export list - - If there is no export list in the module, how does - Haddock generate documentation? Well, when the export list is - omitted, e.g.: - -module Foo where - - this is equivalent to an export list which mentions - every entity defined at the top level in this module, and - Haddock treats it in the same way. Furthermore, the generated - documentation will retain the order in which entities are - defined in the module. In this special case the module body - may also include section headings (normally they would be - ignored by Haddock). - - -module Foo where - --- * This heading will now appear before foo. - --- | Documentation for 'foo'. -foo :: Integer -foo = 5 - - -
-
- -
- Named chunks of documentation - - Occasionally it is desirable to include a chunk of - documentation which is not attached to any particular Haskell - declaration. There are two ways to do this: - - - - The documentation can be included in the export list - directly, e.g.: - - -module Foo ( - -- * A section heading - - -- | Some documentation not attached to a particular Haskell entity - ... - ) where - - - - - If the documentation is large and placing it inline in - the export list might bloat the export list and obscure the - structure, then it can be given a name and placed out of - line in the body of the module. This is achieved with a - special form of documentation annotation - -- $: - - -module Foo ( - -- * A section heading - - -- $doc - ... - ) where - --- $doc --- Here is a large chunk of documentation which may be referred to by --- the name $doc. - - - The documentation chunk is given a name, which is the - sequence of alphanumeric characters directly after the - -- $, and it may be - referred to by the same name in the export list. - - -
- -
- Hyperlinking and re-exported entities - - When Haddock renders a type in the generated - documentation, it hyperlinks all the type constructors and class - names in that type to their respective definitions. But for a - given type constructor or class there may be several modules - re-exporting it, and therefore several modules whose - documentation contains the definition of that type or class - (possibly including the current module!) so which one do we link - to? - - Let's look at an example. Suppose we have three modules - A, B and - C defined as follows: - - -module A (T) where -data T a = C a - -module B (f) where -import A -f :: T Int -> Int -f (C i) = i - -module C (T, f) where -import A -import B - - - Module A exports a datatype - T. Module B imports - A and exports a function f - whose type refers to T. Also, both - T and f are re-exported from - module C. - - Haddock takes the view that each entity has a - home module; that is, the module that the library - designer would most like to direct the user to, to find the - documentation for that entity. So, Haddock makes all links to an entity - point to the home module. The one exception is when the entity is also - exported by the current module: Haddock makes a local link if it - can. - - How is the home module for an entity determined? - Haddock uses the following rules: - - - - If modules A and B both export the entity, and module A imports - (directly or indirectly) module B, then B is preferred. - - - A module with the hide attribute is never - chosen as the home. - - - A module with the not-home attribute is only - chosen if there are no other modules to choose. - - - - If multiple modules fit the criteria, then one is chosen at - random. If no modules fit the criteria (because the candidates are all - hidden), then Haddock will issue a warning for each reference to an - entity without a home. - - In the example above, module A is chosen as the - home for T because it does not import any other - module that exports T. The link from - f's - type in module B will therefore point to - A.T. However, C also exports - T and f, and the link from - f's type in C will therefore - point locally to C.T. -
- -
- Module Attributes - - Certain attributes may be specified for each module which - affects the way that Haddock generates documentation for that - module. Attributes are specified in a comma-separated list in an - {-# OPTIONS_HADDOCK ... #-} pragma at the - top of the module, either before or after the module - description. For example: - - -{-# OPTIONS_HADDOCK hide, prune, ignore-exports #-} - --- |Module description -module A where -... - - - The options and module description can be in either order. - - The following attributes are currently understood by - Haddock: - - - - - hide - hide - - - Omit this module from the generated documentation, - but nevertheless propagate definitions and documentation - from within this module to modules that re-export those - definitions. - - - - - - hide - prune - - - Omit definitions that have no documentation - annotations from the generated documentation. - - - - - - ignore-exports - ignore-exports - - - Ignore the export list. Generate documentation as - if the module had no export list - i.e. all the top-level - declarations are exported, and section headings may be - given in the body of the module. - - - - - - not-home - not-home - - - Indicates that the current module should not be considered to - be the home module for each entity it exports, - unless that entity is not exported from any other module. See - for more details. - - - - - - show-extensions - show-extensions - - - Indicates that we should render the extensions used in this module in the - resulting documentation. This will only render if the output format supports it. - If Language is set, it will be shown as well and all the extensions implied by it won't. - All enabled extensions will be rendered, including those implied by their more powerful versions. - - - - - -
- -
- Markup - - Haddock understands certain textual cues inside - documentation annotations that tell it how to render the - documentation. The cues (or markup) have been - designed to be simple and mnemonic in ASCII so that the - programmer doesn't have to deal with heavyweight annotations - when editing documentation comments. - -
- Paragraphs - - One or more blank lines separates two paragraphs in a - documentation comment. -
- -
- Special characters - - The following characters have special meanings in - documentation comments: \, /, - ', `, - ", @, - <. To insert a literal occurrence of - one of these special characters, precede it with a backslash - (\). - - Additionally, the character > has - a special meaning at the beginning of a line, and the - following characters have special meanings at the beginning of - a paragraph: - *, -. These characters - can also be escaped using \. - - Furthermore, the character sequence >>> - has a special meaning at the beginning of a line. To - escape it, just prefix the characters in the sequence with a - backslash. -
- -
- Character references - - Although Haskell source files may contain any character - from the Unicode character set, the encoding of these characters - as bytes varies between systems, so that only source files - restricted to the ASCII character set are portable. Other - characters may be specified in character and string literals - using Haskell character escapes. To represent such characters - in documentation comments, Haddock supports SGML-style numeric - character references of the forms - &#D; - and - &#xH; - where D and H - are decimal and hexadecimal numbers denoting a code position - in Unicode (or ISO 10646). For example, the references - &#x3BB;, &#x3bb; - and &#955; all represent the lower-case - letter lambda. -
- -
- Code Blocks - - Displayed blocks of code are indicated by surrounding a - paragraph with @...@ or by preceding each - line of a paragraph with > (we often - call these “bird tracks”). For - example: - - --- | This documentation includes two blocks of code: --- --- @ --- f x = x + x --- @ --- --- > g x = x * 42 - - - There is an important difference between the two forms - of code block: in the bird-track form, the text to the right - of the ‘>’ is interpreted - literally, whereas the @...@ form - interprets markup as normal inside the code block. -
- -
- Examples - - Haddock has markup support for examples of interaction with a - read-eval-print loop (REPL). An - example is introduced with - >>> followed by an expression followed - by zero or more result lines: - - --- | Two examples are given below: --- --- >>> fib 10 --- 55 --- --- >>> putStrLn "foo\nbar" --- foo --- bar - - Result lines that only contain the string - <BLANKLINE> are rendered as blank lines in the - generated documentation. -
- -
- Properties - - Haddock provides markup for properties: - --- | Addition is commutative: --- --- prop> a + b = b + a - - This allows third-party applications to extract and verify them. - -
- -
- Hyperlinked Identifiers - - Referring to a Haskell identifier, whether it be a type, - class, constructor, or function, is done by surrounding it - with single quotes: - - --- | This module defines the type 'T'. - - - If there is an entity T in scope in - the current module, then the documentation will hyperlink the - reference in the text to the definition of - T (if the output format supports - hyperlinking, of course; in a printed format it might instead - insert a page reference to the definition). - - It is also possible to refer to entities that are not in - scope in the current module, by giving the full qualified name - of the entity: - - --- | The identifier 'M.T' is not in scope - - - If M.T is not otherwise in scope, - then Haddock will simply emit a link pointing to the entity - T exported from module M - (without checking to see whether either M - or M.T exist). - - To make life easier for documentation writers, a quoted - identifier is only interpreted as such if the quotes surround - a lexically valid Haskell identifier. This means, for - example, that it normally isn't necessary to escape the single - quote when used as an apostrophe: - - --- | I don't have to escape my apostrophes; great, isn't it? - - - Nothing special is needed to hyperlink identifiers which - contain apostrophes themselves: to hyperlink - foo' one would simply type - 'foo''. To hyperlink identifiers written in - infix form, simply put them in quotes as always: - '`elem`'. - - For compatibility with other systems, the following - alternative form of markup is accepted - We chose not to use this as the primary markup for - identifiers because strictly speaking the ` - character should not be used as a left quote, it is a grave accent. - : `T'. -
- -
- Emphasis, Bold and Monospaced text - - Emphasis may be added by surrounding text with - /.../. Other markup is valid inside emphasis. To have a forward - slash inside of emphasis, just escape it: /fo\/o/ - - Bold (strong) text is indicated by surrounding it with __...__. - Other markup is valid inside bold. For example, __/foo/__ will make the emphasised - text foo bold. You don't have to escape a single underscore if you need it bold: - __This_text_with_underscores_is_bold__. - - - Monospaced (or typewriter) text is indicated by - surrounding it with @...@. Other markup is - valid inside a monospaced span: for example - @'f' a b@ will hyperlink the - identifier f inside the code fragment. -
- -
- Linking to modules - - Linking to a module is done by surrounding the module - name with double quotes: - - --- | This is a reference to the "Foo" module. - - - A basic check is done on the syntax of the header name to ensure that it is valid - before turning it into a link but unlike with identifiers, whether the module is in scope isn't checked - and will always be turned into a link. - - -
- -
- Itemized and Enumerated lists - - A bulleted item is represented by preceding a paragraph - with either * or - -. A sequence of bulleted - paragraphs is rendered as an itemized list in the generated - documentation, eg.: - - --- | This is a bulleted list: --- --- * first item --- --- * second item - - - An enumerated list is similar, except each paragraph - must be preceded by either - (n) - or - n. - where n is any integer. e.g. - - --- | This is an enumerated list: --- --- (1) first item --- --- 2. second item - - - Lists of the same type don't have to be separated by a newline: - --- | This is an enumerated list: --- --- (1) first item --- 2. second item --- --- This is a bulleted list: --- --- * first item --- * second item - - - You can have more than one line of content in a list element: - - --- | --- * first item --- and more content for the first item --- * second item --- and more content for the second item - - - You can even nest whole paragraphs inside of list elements. The rules - are 4 spaces for each indentation level. You're required to use a newline before - such nested paragraph: - - -{-| -* Beginning of list -This belongs to the list above! - - > nested - > bird - > tracks - - * Next list - More of the indented list. - - * Deeper - - @ - even code blocks work - @ - - * Deeper - - 1. Even deeper! - 2. No newline separation even in indented lists. --} - - The indentation of the first list item is honoured. That is, - in the following example the items are on the same level. Before - Haddock 2.16.1, the second item would have been nested under the - first item which was unexpected. - - -{-| - * foo - - * bar --} - -
- -
- Definition lists - - Definition lists are written as follows: - - --- | This is a definition list: --- --- [@foo@]: The description of @foo@. --- --- [@bar@]: The description of @bar@. - - - To produce output something like this: - - - - foo - - The description of foo. - - - - bar - - The description of bar. - - - - - Each paragraph should be preceded by the - “definition term” enclosed in square brackets and followed by a colon. - Other markup operators may be used freely within the - definition term. You can escape ] with a backslash as usual. - - Same rules about nesting and no newline separation as for bulleted and numbered lists apply. - - -
- -
- URLs - - - A URL can be included in a documentation comment by surrounding it in - angle brackets, for example: - - - -<http://example.com> - - - - If the output format supports it, the URL will be turned into a - hyperlink when rendered. - - - If Haddock sees something that looks like a URL (such as something starting with - http:// or ssh://) where the URL markup is valid, - it will automatically make it a hyperlink. -
- -
- Links - - - Haddock supports Markdown syntax for inline links. A link consists - of a link text and a URL. The link text is enclosed in square - brackets and followed by the URL enclosed in regular parentheses, for - example: - - - -[some link](http://example.com) - - - The link text is used as a descriptive text for the URL, if the - output format supports it. - -
- -
- Images - - Haddock supports Markdown syntax for inline images. This resembles - the syntax for links, but starts with an exclamation mark. An - example looks like this: - - - -![image description](pathtoimage.png) - - - If the output format supports it, the image will be rendered inside - the documentation. The image description is used as relpacement text - and/or image title. - -
- -
- Anchors - - Sometimes it is useful to be able to link to a point in - the documentation which doesn't correspond to a particular - entity. For that purpose, we allow anchors to be - included in a documentation comment. The syntax is - #label#, where - label is the name of the anchor. - An anchor is invisible in the generated documentation. - - To link to an anchor from elsewhere, use the syntax - "module#label" - where module is the module name - containing the anchor, and label is - the anchor label. The module does not have to be local, it can - be imported via an interface. Please note that in Haddock - versions 2.13.x and earlier, the syntax was - "module\#label". - It is considered deprecated and will be removed in the future. -
- -
- Headings - Headings inside of comment documentation are possible be preceding them with - a number of =s. From 1 to 6 are accepted. Extra =s will - be treated as belonging to the text of the heading. Note that it's up to the output format to decide - how to render the different levels. - - - --- | --- = Heading level 1 with some /emphasis/ --- Something underneath the heading. --- --- == /Subheading/ --- More content. --- --- === Subsubheading --- Even more content. - - - Note that while headings have to start on a new paragraph, we allow paragraph-level content to - follow these immediately. - - - --- | --- = Heading level 1 with some __bold__ --- Something underneath the heading. --- --- == /Subheading/ --- More content. --- --- === Subsubheading --- >>> examples are only allowed at the start of paragraphs - - - As of 2.15.1, there's experimental (read: subject to - change or get removed) support for collapsible headers: simply - wrap your existing header title in underscores, as per bold - syntax. The collapsible section will stretch until the end of - the comment or until a header of equal or smaller number of - =s. - - --- | --- === __Examples:__ --- >>> Some very long list of examples --- --- ==== This still falls under the collapse --- Some specialised examples --- --- === This is does not go into the collapsable section. --- More content. - - -
- -
- Metadata - Since Haddock 2.16.0, some support for embedding - metadata in the comments has started to appear. The use of - such data aims to standardise various community conventions in - how such information is conveyed and to provide uniform - rendering. - - -
- Since - @since annotation can be used to - convey information about when the function was introduced or - when it has changed in the way significant to the user. - @since is a paragraph-level element. - While multiple such annotations are not an error, only the - one to appear in the comment last will be used. - @since has to be followed with a version - number, no further description is currently allowed. The - meaning of this feature is subject to change in the future - per user feedback. - - - --- | --- Some comment --- --- @since 1.2.3 - - -
- -
- -
- - - diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 00000000..dc30c45f --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,21 @@ +Welcome to Haddock's documentation! +=================================== + +This is Haddock, a tool for automatically generating documentation from +annotated Haskell source code. + +Contents: + +.. toctree:: + :maxdepth: 2 + + intro + invoking + markup + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/doc/intro.rst b/doc/intro.rst new file mode 100644 index 00000000..fcdc67f1 --- /dev/null +++ b/doc/intro.rst @@ -0,0 +1,164 @@ +Introduction +============ + +This is Haddock, a tool for automatically generating documentation from +annotated Haskell source code. Haddock was designed with several goals +in mind: + +- When documenting APIs, it is desirable to keep the documentation + close to the actual interface or implementation of the API, + preferably in the same file, to reduce the risk that the two become + out of sync. Haddock therefore lets you write the documentation for + an entity (function, type, or class) next to the definition of the + entity in the source code. + +- There is a tremendous amount of useful API documentation that can be + extracted from just the bare source code, including types of exported + functions, definitions of data types and classes, and so on. Haddock + can therefore generate documentation from a set of straight Haskell + 98 modules, and the documentation will contain precisely the + interface that is available to a programmer using those modules. + +- Documentation annotations in the source code should be easy on the + eye when editing the source code itself, so as not to obscure the + code and to make reading and writing documentation annotations easy. + The easier it is to write documentation, the more likely the + programmer is to do it. Haddock therefore uses lightweight markup in + its annotations, taking several ideas from + `IDoc `__. In fact, + Haddock can understand IDoc-annotated source code. + +- The documentation should not expose any of the structure of the + implementation, or to put it another way, the implementer of the API + should be free to structure the implementation however he or she + wishes, without exposing any of that structure to the consumer. In + practical terms, this means that while an API may internally consist + of several Haskell modules, we often only want to expose a single + module to the user of the interface, where this single module just + re-exports the relevant parts of the implementation modules. + + Haddock therefore understands the Haskell module system and can + generate documentation which hides not only non-exported entities + from the interface, but also the internal module structure of the + interface. A documentation annotation can still be placed next to the + implementation, and it will be propagated to the external module in + the generated documentation. + +- Being able to move around the documentation by following hyperlinks + is essential. Documentation generated by Haddock is therefore + littered with hyperlinks: every type and class name is a link to the + corresponding definition, and user-written documentation annotations + can contain identifiers which are linked automatically when the + documentation is generated. + +- We might want documentation in multiple formats - online and printed, + for example. Haddock comes with HTML, LaTeX, and Hoogle backends, and + it is structured in such a way that adding new backends is + straightforward. + +Obtaining Haddock +----------------- + +Distributions (source & binary) of Haddock can be obtained from its `web +site `__. + +Up-to-date sources can also be obtained from our public darcs +repository. The Haddock sources are at +``http://code.haskell.org/haddock``. See +`darcs.net `__ for more information on the darcs +version control utility. + +License +------- + +The following license covers this documentation, and the Haddock source +code, except where otherwise indicated. + + Copyright 2002-2010, Simon Marlow. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + - Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + - Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS IS" AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE + LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Contributors +------------ + +Haddock was originally written by Simon Marlow. Since it is an open +source project, many people have contributed to its development over the +years. Below is a list of contributors in alphabetical order that we +hope is somewhat complete. If you think you are missing from this list, +please contact us. + +- Ashley Yakeley +- Benjamin Franksen +- Brett Letner +- Clemens Fruhwirth +- Conal Elliott +- David Waern +- Duncan Coutts +- George Pollard +- George Russel +- Hal Daume +- Ian Lynagh +- Isaac Dupree +- Joachim Breitner +- Krasimir Angelov +- Lennart Augustsson +- Luke Plant +- Malcolm Wallace +- Manuel Chakravarty +- Mark Lentczner +- Mark Shields +- Mateusz Kowalczyk +- Mike Thomas +- Neil Mitchell +- Oliver Brown +- Roman Cheplyaka +- Ross Paterson +- Sigbjorn Finne +- Simon Hengel +- Simon Marlow +- Simon Peyton-Jones +- Stefan O'Rear +- Sven Panne +- Thomas Schilling +- Wolfgang Jeltsch +- Yitzchak Gale + +Acknowledgements +---------------- + +Several documentation systems provided the inspiration for Haddock, most +notably: + +- `IDoc `__ + +- `HDoc `__ + +- `Doxygen `__ + +and probably several others I've forgotten. + +Thanks to the the members of haskelldoc@haskell.org, +haddock@projects.haskell.org and everyone who contributed to the many +libraries that Haddock makes use of. diff --git a/doc/invoking.rst b/doc/invoking.rst new file mode 100644 index 00000000..38ba7551 --- /dev/null +++ b/doc/invoking.rst @@ -0,0 +1,454 @@ +Invoking Haddock +================ + +Haddock is invoked from the command line, like so: + +.. code-block:: none + + 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 :option:`-h` option for HTML and the :option:`--hoogle` option for outputting +Hoogle data are functional. + +The packaging tool +`Cabal `__ +has Haddock support, and is often used instead of invoking Haddock +directly. + +The following options are available: + +.. program:: haddock + +.. option:: -B + + Tell GHC that that its lib directory is dir. Can be used to override + the default path. + +.. option:: -o + --odir= + + Generate files into dir instead of the current directory. + +.. option:: -l + --lib= + + Use Haddock auxiliary files (themes, javascript, etc...) in dir. + +.. option:: -i + --read-interface= + -i , + --read-interface=, + -i ,, + --read-interface=,, + + Read the interface file in file, which must have been produced by + running Haddock with the :option:`--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 :option:`--hyperlinked-source` + option. + + Multiple :option:`--read-interface` options may be given. + +.. option:: -D + --dump-interface= + + 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 + :option:`--read-interface` option for more details. The interface file is + in a binary format; don't try to read it. + +.. [1] + Haddock interface files are not the same as Haskell interface files, + I just couldn't think of a better name. + +.. option:: -h + --html + + Generate documentation in HTML format. Several files will be + generated into the current directory (or the specified directory if + the :option:`-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 in frames. + + ``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. + + ``frames.html`` + The top level document when viewing in frames. + + ``some.css``; ``etc...`` + Files needed for the themes used. Specify your themes using the + :option:`--theme` option. + + ``haddock-util.js`` + Some JavaScript utilities used to implement some of the dynamic + features like collapsible sections, and switching to frames + view. + +.. option:: --latex + + Generate documentation in LaTeX format. Several files will be + generated into the current directory (or the specified directory if + the :option:`-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 :option:`--latex-style` + option. + + ``module.tex`` + The LaTeX documentation for each module. + +.. option:: --latex-style=