aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMarcin Szamotulski <profunctor@pm.me>2021-04-17 16:06:56 +0200
committerMarcin Szamotulski <profunctor@pm.me>2021-06-02 08:57:24 +0200
commit9c25808e32bdf67825720871a0a0da2c019721a1 (patch)
treea685ff995b7ad0313a41f4d7e2516e8103abaf59
parent00f5c93617697c725ec33e06d72685b3c8241a92 (diff)
Document multi component support
-rw-r--r--doc/index.rst1
-rw-r--r--doc/multi-components.rst48
2 files changed, 49 insertions, 0 deletions
diff --git a/doc/index.rst b/doc/index.rst
index d800a2b9..f370e42f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -13,6 +13,7 @@ Contents:
invoking
markup
common-errors
+ multi-components
Indices and tables
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>`_.