From 00f5c93617697c725ec33e06d72685b3c8241a92 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Sat, 17 Apr 2021 15:37:25 +0200 Subject: Added myself to contributors --- doc/intro.rst | 1 + 1 file changed, 1 insertion(+) 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 -- cgit v1.2.3 From 9c25808e32bdf67825720871a0a0da2c019721a1 Mon Sep 17 00:00:00 2001 From: Marcin Szamotulski Date: Sat, 17 Apr 2021 16:06:56 +0200 Subject: Document multi component support --- doc/index.rst | 1 + doc/multi-components.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 doc/multi-components.rst diff --git a/doc/index.rst b/doc/index.rst index d800a2b9..f370e42f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -13,6 +13,7 @@ Contents: invoking markup common-errors + multi-components Indices and tables 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