From ff6c624da2e0ec9fa766eb866075176cde4e0e39 Mon Sep 17 00:00:00 2001 From: CGenie Date: Mon, 31 May 2021 09:02:13 +0200 Subject: Add page about common errors (#1396) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update index.rst Common errors page * Create common-errors.rst * Update common-errors.rst * Use GHC 9.2 in CI runner (#1378) * [haddock-api] remove .hspec-failures Co-authored-by: Hécate Moonlight --- doc/index.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/index.rst') diff --git a/doc/index.rst b/doc/index.rst index dc30c45f..d800a2b9 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -12,6 +12,7 @@ Contents: intro invoking markup + common-errors Indices and tables -- 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 (limited to 'doc/index.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