From e1faf47c26522e95932e5d9cf8e5623a9f3480e1 Mon Sep 17 00:00:00 2001
From: Marcin Szamotulski <profunctor@pm.me>
Date: Sat, 17 Apr 2021 16:06:56 +0200
Subject: [PATCH] Document multi component support

---
 doc/index.rst            |  1 +
 doc/multi-components.rst | 45 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)
 create mode 100644 doc/multi-components.rst

diff --git a/doc/index.rst b/doc/index.rst
index dc30c45f04..0d1b8b480b 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/multi-components.rst b/doc/multi-components.rst
new file mode 100644
index 0000000000..a5eb3f2cab
--- /dev/null
+++ b/doc/multi-components.rst
@@ -0,0 +1,45 @@
+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 file 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
+
+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>`_.