diff options
| author | Hécate Moonlight <Kleidukos@users.noreply.github.com> | 2021-06-02 09:35:55 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-06-02 09:35:55 +0200 |
| commit | 140fc2ce530bf963e5329252d59219083257ac47 (patch) | |
| tree | a685ff995b7ad0313a41f4d7e2516e8103abaf59 | |
| parent | ff6c624da2e0ec9fa766eb866075176cde4e0e39 (diff) | |
| parent | 9c25808e32bdf67825720871a0a0da2c019721a1 (diff) | |
Merge pull request #1379 from coot/coot/document-multi-component-support
Document multi component support
| -rw-r--r-- | doc/index.rst | 1 | ||||
| -rw-r--r-- | doc/intro.rst | 1 | ||||
| -rw-r--r-- | doc/multi-components.rst | 48 |
3 files changed, 50 insertions, 0 deletions
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/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/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>`_. |