Skip to content

Commit

Permalink
Merge pull request haskell#8119 from haskell/doc-haddock
Browse files Browse the repository at this point in the history 
Doc: Fix command-line syntax for haddock options; add --haddock-quickjump
  • Loading branch information
@mergify
mergify[bot] authored May 4, 2022
2 parents 63841fb + bb4a340 commit a72bb45
Showing 1 changed file with 48 additions and 61 deletions.
109 changes: 48 additions & 61 deletions doc/cabal-project.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ options):

4. ``cabal.project.local`` (the output of ``cabal configure``)

Any call to ``cabal build`` will consider ``cabal.project*`` files from parent
Any call to ``cabal build`` will consider ``cabal.project*`` files from parent
directories when there is none in the current directory.

.. _conditionals and imports:
Expand Down Expand Up @@ -312,7 +312,7 @@ package, and thus apply globally:
Nix-style local build cache
in-place
Project-specific build directory

By default, the package stack you will have with v2 commands is:

::
Expand All @@ -328,7 +328,7 @@ package, and thus apply globally:
::

-- [global, store, in-place]

So your local packages get put in ``dist-newstyle`` instead of the store.

This flag manipulates the default prefix: ``[global, store]`` and accepts
Expand Down Expand Up @@ -1316,15 +1316,18 @@ Haddock options

:default: False

Enables building of Haddock documentation
Enables building of Haddock documentation.

The command line variant of this flag is ``--enable-documentation``
and ``--disable-documentation``.

`documentation: true` does not imply :cfg-field:`haddock-benchmarks`,
:cfg-field:`haddock-executables`, :cfg-field:`haddock-internal` or
:cfg-field:`haddock-tests`. These need to be enabled separately if
desired.
`documentation: true` does not imply
:cfg-field:`haddock-all`,
:cfg-field:`haddock-benchmarks`,
:cfg-field:`haddock-executables`,
:cfg-field:`haddock-internal` or
:cfg-field:`haddock-tests`.
These need to be enabled separately if desired.

.. cfg-field:: doc-index-file: templated path
--doc-index-file=TEMPLATE
Expand All @@ -1333,156 +1336,140 @@ Haddock options
A central index of Haddock API documentation (template cannot use
``$pkgid``), which should be updated as documentation is built.

The command line variant of this flag is
``--doc-index-file=TEMPLATE``

The following commands are equivalent to ones that would be passed when
running ``setup haddock``. (TODO: Where does the documentation get put.)
running ``setup haddock``.

.. cfg-field:: haddock-hoogle: boolean
--haddock-hoogle
:synopsis: Generate Hoogle file.

:default: False

Generate a text file which can be converted by Hoogle_
into a database for searching. This is equivalent to running ``haddock``
with the ``--hoogle`` flag.

The command line variant of this flag is ``--hoogle`` (for the
``haddock`` command).
into a database for searching.
This is equivalent to running ``haddock`` with the ``--hoogle`` flag.

.. cfg-field:: haddock-html: boolean
--haddock-html
:synopsis: Build HTML documentation.

:default: True

Build HTML documentation.

The command line variant of this flag is ``--html`` (for the
``haddock`` command).
.. cfg-field:: haddock-quickjump: boolean
--haddock-quickjump
:synopsis: Generate Quickjump file.

:default: False

Generate an index for interactive documentation navigation.
This is equivalent to running ``haddock`` with the ``--quickjump`` flag.

.. cfg-field:: haddock-html-location: templated path
--html-location=TEMPLATE
--haddock-html-location=TEMPLATE
:synopsis: Haddock HTML templates location.

Specify a template for the location of HTML documentation for
prerequisite packages. The substitutions are applied to the template
to obtain a location for each package, which will be used by
hyperlinks in the generated documentation. For example, the
following command generates links pointing at [Hackage] pages:
following command generates links pointing at Hackage pages:

::

html-location: http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html

The command line variant of this flag is ``--html-location`` (for
the ``haddock`` subcommand).
If passed on the command line,
the argument may be quoted to prevent substitution by the shell.

::

--html-location='http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html'

Here the argument is quoted to prevent substitution by the shell. If
this option is omitted, the location for each package is obtained
If this option is omitted, the location for each package is obtained
using the package tool (e.g. ``ghc-pkg``).

.. cfg-field:: haddock-executables: boolean
--haddock-executables
:synopsis: Generate documentation for executables.

:default: False

Run haddock on all executable programs.

The command line variant of this flag is ``--executables`` (for the
``haddock`` subcommand).

.. cfg-field:: haddock-tests: boolean
--haddock-tests
:synopsis: Generate documentation for tests.

:default: False

Run haddock on all test suites.

The command line variant of this flag is ``--tests`` (for the
``haddock`` subcommand).

.. cfg-field:: haddock-benchmarks: boolean
--haddock-benchmarks
:synopsis: Generate documentation for benchmarks.

:default: False

Run haddock on all benchmarks.

The command line variant of this flag is ``--benchmarks`` (for the
``haddock`` subcommand).

.. cfg-field:: haddock-all: boolean
:synopsis: Generate documentation for everything

:default: False

Run haddock on all components.

The command line variant of this flag is ``--all`` (for the
``haddock`` subcommand).

.. cfg-field:: haddock-internal: boolean
--haddock-internal
:synopsis: Generate documentation for internal modules

:default: False

Build haddock documentation which includes unexposed modules and
symbols.

The command line variant of this flag is ``--internal`` (for the
``haddock`` subcommand).
.. cfg-field:: haddock-all: boolean
--haddock-all
:synopsis: Generate documentation for everything

:default: False

Run haddock on all components.

.. cfg-field:: haddock-css: path
--haddock-css=PATH
:synopsis: Location of Haddock CSS file.

The CSS file that should be used to style the generated
documentation (overriding haddock's default.)

The command line variant of this flag is ``--css`` (for the
``haddock`` subcommand).
documentation (overriding haddock's default).

.. cfg-field:: haddock-hyperlink-source: boolean
--haddock-hyperlink-source
:synopsis: Generate hyperlinked source code for documentation

:default: False

Generated hyperlinked source code using `HsColour`_, and have
Haddock documentation link to it.

The command line variant of this flag is ``--hyperlink-source`` (for
the ``haddock`` subcommand).
This is equivalent to running ``haddock`` with the ``--hyperlinked-source`` flag.

.. cfg-field:: haddock-hscolour-css: path
--haddock-hscolour-css=PATH
:synopsis: Location of CSS file for HsColour

The CSS file that should be used to style the generated hyperlinked
source code (from `HsColour`_).

The command line variant of this flag is ``--hscolour-css`` (for the
``haddock`` subcommand).

.. cfg-field:: haddock-contents-location: URL
--haddock-contents-location=URL
:synopsis: URL for contents page.

A baked-in URL to be used as the location for the contents page.

The command line variant of this flag is ``--contents-location``
(for the ``haddock`` subcommand).

.. cfg-field:: haddock-keep-temp-files: boolean
:synopsis: Keep temporary Haddock files.

Keep temporary files.

The command line variant of this flag is ``--keep-temp-files`` (for
the ``haddock`` subcommand).
There is no command line variant of this flag.

.. cfg-field:: open: boolean
--open
:synopsis: Open generated documentation in-browser.

When generating HTML documentation, attempt to open it in a browser
Expand Down

0 comments on commit a72bb45

Please sign in to comment.