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 ".".

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