From 1b63771dee5a7fac0696505d0b335908bd12835d Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Mon, 16 Aug 2021 08:46:03 +0200 Subject: 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 ".". --- doc/index.rst | 1 + doc/intro.rst | 1 + doc/invoking.rst | 7 +++++++ doc/multi-components.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 57 insertions(+) create mode 100644 doc/multi-components.rst (limited to 'doc') 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= + + 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= --source-module= --source-entity= 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 +`_, which haddocks are served on +`github-pages `_. -- cgit v1.2.3