coot/multiple package (ghc-head)

doc/index.rst

@@ -12,6 +12,7 @@ Contents:
    intro
    invoking
    markup
+   multi-components
 
 
 Indices and tables

doc/intro.rst

@@ -125,6 +125,7 @@ please contact us.
 -  Luke Plant
 -  Malcolm Wallace
 -  Manuel Chakravarty
+-  Marcin Szamotulski
 -  Mark Lentczner
 -  Mark Shields
 -  Mateusz Kowalczyk

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>

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

haddock-api/haddock-api.cabal

@@ -48,6 +48,7 @@ library
                , ghc-paths       ^>= 0.1.0.9
                , haddock-library ^>= 1.9.0
                , xhtml           ^>= 3000.2.2
+               , parsec          ^>= 3.1.13.0
 
   -- Versions for the dependencies below are transitively pinned by
   -- the non-reinstallable `ghc` package and hence need no version
@@ -93,6 +94,8 @@ library
     Haddock.Parser
     Haddock.Utils
     Haddock.Utils.Json
+    Haddock.Utils.Json.Types
+    Haddock.Utils.Json.Parser
     Haddock.Backends.Xhtml
     Haddock.Backends.Xhtml.Decl
     Haddock.Backends.Xhtml.DocMarkup
@@ -169,6 +172,8 @@ test-suite spec
     Haddock.Types
     Haddock.Utils
     Haddock.Utils.Json
+    Haddock.Utils.Json.Types
+    Haddock.Utils.Json.Parser
     Haddock.Version
     Paths_haddock_api
     Haddock.Backends.Hyperlinker.ParserSpec
@@ -180,6 +185,7 @@ test-suite spec
                , haddock-library ^>= 1.9.0
                , xhtml           ^>= 3000.2.2
                , hspec           >= 2.4.4 && < 2.8
+               , parsec          ^>= 3.1.13.0
                , QuickCheck      >= 2.11  && ^>= 2.14
 
   -- Versions for the dependencies below are transitively pinned by

haddock-api/resources/html/js-src/init.ts

@@ -17,6 +17,11 @@ function onDomReady(callback: () => void) {
 onDomReady(() => {
   document.body.classList.add('js-enabled');
   styleMenu.init();
-  quickJump.init();
   detailsHelper.init();
+  let head = document.getElementById('head');
+  let baseURL = ".";
+  if (head !== null) {
+    baseURL = head.getAttribute('data-base-url') || '.';
+  }
+  quickJump.init(baseURL);
 });