coot/multiple package (ghc-head) (#1419)

* FromJSON class

Aeson style FromJSON class with Parsec based json parser.

* doc-index.json file for multiple packages

When creating haddock summary page for multiple packages render
doc-index.json file using contents of all found 'doc-index.json' files.

* Render doc-index.json

When rendering html, render doc-index.json file independently of
maybe_index_url option.  doc-index.json file is useful now even if
maybe_index_url is not `Nothing`.

* base url option

New `Flag_BaseURL` which configures from where static files are loaded
(--base-url).  If given and not equal "." static files are not coppied,
as this indicates that they are not read from the the directory where
we'd copy them.  The default value is ".".

1 files changed, 48 insertions, 0 deletions

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>`_.