diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/index.rst | 1 | ||||
| -rw-r--r-- | doc/intro.rst | 1 | ||||
| -rw-r--r-- | doc/invoking.rst | 7 | ||||
| -rw-r--r-- | doc/multi-components.rst | 48 |
4 files changed, 57 insertions, 0 deletions
diff --git a/doc/index.rst b/doc/index.rst index dc30c45f..0d1b8b48 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -12,6 +12,7 @@ Contents: intro invoking markup + multi-components Indices and tables diff --git a/doc/intro.rst b/doc/intro.rst index a3497426..fc1269f9 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -125,6 +125,7 @@ please contact us. - Luke Plant - Malcolm Wallace - Manuel Chakravarty +- Marcin Szamotulski - Mark Lentczner - Mark Shields - Mateusz Kowalczyk diff --git a/doc/invoking.rst b/doc/invoking.rst index 4e4b8764..68e01d70 100644 --- a/doc/invoking.rst +++ b/doc/invoking.rst @@ -223,6 +223,13 @@ The following options are available: Reserved for future use (output documentation in DocBook XML format). +.. option:: --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. + .. option:: --source-base=<url> --source-module=<url> --source-entity=<url> diff --git a/doc/multi-components.rst b/doc/multi-components.rst new file mode 100644 index 00000000..9f52cad3 --- /dev/null +++ b/doc/multi-components.rst @@ -0,0 +1,48 @@ +Haddocks of multiple components +=============================== + +Haddock supports building documentation of multiple components. First, one +needs to build haddocks of all components which can be done with: + +.. code-block:: none + + cabal haddock --haddock-html \ + --haddock-quickjump \ + --haddock-option="--use-index=../doc-index.html" \ + --haddock-option="--use-contents=../index.html" \ + --haddock-option="--base-url=.." \ + all + +The new ``--base-url`` option will allow to access the static files from the +main directory (in this example its the relative ``./..`` directory). It will +also prevent ``haddock`` from copying its static files to each of the +documentation folders, we're only need a single copy of them where the +``--base-url`` option points to. + +The second step requires to copy all the haddocks to a common directory, let's +say ``./docs``, this will depend on your project and it might look like: + +.. code-block:: none + + cp -r dist-newstyle/build/x86_64-linux/ghc-9.0.1/package-a-0.1.0.0/doc/html/package-a/ docs + cp -r dist-newstyle/build/x86_64-linux/ghc-9.0.1/package-b-0.1.0.0/doc/html/package-b/ docs + +Note that you can also include documentation of other packages in this way, +e.g. ``base``, but you need to know where it is hidden on your hard-drive. + +To build html and js (``quickjump``) indexes one can now invoke ``haddock`` with: + +.. code-block:: none + + haddock \ + -o docs \ + --quickjump --gen-index --gen-contents \ + --read-interface=package-a,docs/package-a/package-a.haddock \ + --read-interface=package-b,docs/package-b/package-b.haddock + +Note: the ``PATH`` in ``--read-interface=PATH,...`` must be a relative url of +a package it points to (relative to the ``docs`` directory). + +There's an example project which shows how to do that posted `here +<https://github.com/coot/haddock-example>`_, which haddocks are served on +`github-pages <https://coot.github.io/haddock-example>`_. |