diff options
| -rw-r--r-- | .github/workflows/ci.yml | 11 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 16 | ||||
| -rw-r--r-- | README.md | 4 | ||||
| -rw-r--r-- | cabal.project | 189 | ||||
| -rw-r--r-- | doc/common-errors.rst | 19 | ||||
| -rw-r--r-- | doc/index.rst | 2 | ||||
| -rw-r--r-- | doc/intro.rst | 1 | ||||
| -rw-r--r-- | doc/multi-components.rst | 48 | ||||
| -rw-r--r-- | haddock-api/haddock-api.cabal | 13 | ||||
| -rw-r--r-- | haddock-library/haddock-library.cabal | 9 | ||||
| -rw-r--r-- | haddock-test/src/Test/Haddock/Config.hs | 2 | ||||
| -rw-r--r-- | haddock.cabal | 6 |
12 files changed, 284 insertions, 36 deletions
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b2b882e3..4baa2fc5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -4,7 +4,7 @@ name: CI on: pull_request: push: - branches: ["ghc-9.0"] + branches: ["ghc-9.2"] jobs: cabal: @@ -15,11 +15,11 @@ jobs: os: [ubuntu-latest] cabal: ["3.4"] ghc: - - "9.0.1" + - "9.2.0.20210422" steps: - uses: actions/checkout@v2 - if: github.event.action == 'opened' || github.event.action == 'synchronize' || github.event.ref == 'refs/heads/ghc-9.0' + if: github.event.action == 'opened' || github.event.action == 'synchronize' || github.event.ref == 'refs/heads/ghc-9.2' - uses: haskell/actions/setup@v1 id: setup-haskell-cabal @@ -37,12 +37,11 @@ jobs: cabal freeze - uses: actions/cache@v2 - name: Cache ~/.cabal/store and .ghcup + name: Cache ~/.cabal/store with: path: | ${{ steps.setup-haskell-cabal.outputs.cabal-store }} - .ghcup - key: ${{ runner.os }} + key: ${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('cabal.project.freeze') }} - name: Build run: | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e1aeca6..9e7fe5c2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,20 +44,20 @@ so that documentation built within GHC can benefit from it. #### Using `cabal` -Requires cabal `>= 3.4` and GHC `== 9.0`: +Requires cabal `>= 3.4` and GHC `== 9.2`: + +First update the package list: ```bash -cabal v2-build all --enable-tests -cabal v2-test all +cabal v2-update ``` -#### Using `stack` +This is needed as haddock@ghc-9.2 uses the +[ghc.head](https://ghc.gitlab.haskell.org/head.hackage/) package repository. ```bash -stack init -stack build -export HADDOCK_PATH="$(stack exec which haddock)" -stack test +cabal v2-build all --enable-tests +cabal v2-test all ``` ### Updating golden testsuite outputs @@ -25,8 +25,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) to see how to make contributions to the project. -[CI page]: https://travis-ci.org/haskell/haddock -[CI badge]: https://travis-ci.org/haskell/haddock.svg?branch=ghc-8.10 +[CI page]: https://github.com/haskell/haddock/actions/workflows/ci.yml +[CI badge]: https://github.com/haskell/haddock/actions/workflows/ci.yml/badge.svg [Hackage page]: https://hackage.haskell.org/package/haddock [Hackage badge]: https://img.shields.io/hackage/v/haddock.svg [ReST]: http://www.sphinx-doc.org/en/stable/rest.html diff --git a/cabal.project b/cabal.project index 2525070a..bac38a52 100644 --- a/cabal.project +++ b/cabal.project @@ -3,12 +3,189 @@ packages: ./ ./haddock-library ./haddock-test -with-compiler: ghc-9.0 +with-compiler: ghc-9.2 + +active-repositories: hackage.haskell.org, head.hackage.ghc.haskell.org:override allow-newer: - ghc-paths:Cabal, - *:base, - *:ghc-prim + Cabal, + base, + binary, + bytestring, + ghc, + ghc-prim, + integer-gmp, + template-haskell, + text, + time + +repository head.hackage.ghc.haskell.org + url: https://ghc.gitlab.haskell.org/head.hackage/ + secure: True + key-threshold: 3 + root-keys: + f76d08be13e9a61a377a85e2fb63f4c5435d40f8feb3e12eb05905edb8cdea89 + 26021a13b401500c8eb2761ca95c61f2d625bfef951b939a8124ed12ecf07329 + 7541f32a4ccca4f97aea3b22f5e593ba2c0267546016b992dfadcd2fe944e55d --- Pinning the index-state helps to make reasonably CI deterministic -index-state: 2021-01-24T12:09:34Z +constraints: + Cabal ==2.4.1.0 || ==3.0.2.0 || ==3.2.1.0, + EdisonAPI ==1.3.1, + EdisonCore ==1.3.2.1, + FPretty ==1.1, + HTTP ==4000.3.16, + HUnit ==1.6.2.0, + QuickCheck ==2.14.2, + Spock-core ==0.14.0.0, + active ==0.2.0.14, + aeson ==1.5.6.0, + aivika ==5.9.1, + aivika-transformers ==5.9.1, + alex ==3.2.6, + ansi-pretty ==0.1.2.2, + arith-encode ==1.0.2, + attoparsec ==0.13.2.5 || ==0.14.1, + barbies ==2.0.2.0, + barbies-th ==0.1.8, + base-compat ==0.11.2, + base-compat-batteries ==0.11.2, + base16-bytestring ==1.0.1.0, + basement ==0.0.12, + bits ==0.5.3, + blaze-builder ==0.4.2.1, + boomerang ==1.4.7, + bound ==2.0.3, + box-tuples ==0.2.0.4, + byteslice ==0.2.5.2, + bytesmith ==0.3.7.0, + bytestring-strict-builder ==0.4.5.4, + cabal-doctest ==1.0.8, + cantor-pairing ==0.2.0.1, + cassava ==0.5.2.0, + cborg ==0.2.5.0, + cereal ==0.5.8.1, + charset ==0.3.8, + chaselev-deque ==0.5.0.5, + colour ==2.3.5, + combinat ==0.2.10.0, + commonmark-extensions ==0.2.0.4, + conduit ==1.3.4.1, + constraints ==0.13, + constraints-extras ==0.3.1.0, + cql ==4.0.3, + critbit ==0.2.0.0, + cryptonite ==0.28 || ==0.29, + data-default-instances-new-base ==0.0.2, + data-dword ==0.3.2, + data-r-tree ==0.6.0, + deferred-folds ==0.9.17, + deriving-compat ==0.5.10, + diagrams-lib ==1.4.3, + doctest ==0.16.3 || ==0.18.1, + drinkery ==0.4, + emacs-module ==0.1.1, + endo ==0.3.0.1, + entropy ==0.4.1.6, + enumeration ==0.2.0, + extra ==1.7.9, + fclabels ==2.0.5, + filepattern ==0.1.2, + focus ==1.0.2, + free-algebras ==0.1.0.1, + free-functors ==1.2.1, + generic-deriving ==1.14, + generic-lens ==2.1.0.0, + generic-lens-core ==2.1.0.0, + generic-optics ==2.1.0.0, + generics-sop ==0.5.1.1, + happy ==1.20.0, + hashtables ==1.2.4.1, + haskeline ==0.7.5.0, + haskell-src-exts ==1.23.1, + haskell-src-meta ==0.8.7, + heterocephalus ==1.0.5.4, + hgeometry ==0.11.0.0, + hgeometry-ipe ==0.11.0.0, + hspec-discover ==2.8.2, + hspec-expectations ==0.8.2, + hspec-meta ==2.7.8, + hspec-wai ==0.11.1, + http-types ==0.12.3, + http2 ==3.0.1, + hvect ==0.4.0.0, + hxt ==9.3.1.22, + inj-base ==0.2.0.0, + inspection-testing ==0.4.5.0, + integer-roots ==1.0, + invariant ==0.5.4, + io-choice ==0.0.7, + iproute ==1.7.11, + language-haskell-extract ==0.2.4, + lens ==4.19.2 || ==5.0.1, + lens-family-th ==0.5.2.0, + list-t ==1.0.4, + memory ==0.15.0 || ==0.16.0, + monad-validate ==1.2.0.0, + monadplus ==1.4.2, + mono-traversable ==1.0.15.1, + mono-traversable-keys ==0.1.0, + mustache ==2.3.1, + network ==3.1.2.1, + newtype-generics ==0.6, + numtype-dk ==0.5.0.2, + obdd ==0.8.2, + packman ==0.5.0, + pandoc ==2.13, + parameterized-utils ==2.1.3.0, + partial-isomorphisms ==0.2.2.1, + plots ==0.1.1.2, + pointed ==5.0.2, + posix-api ==0.3.4.0, + primitive ==0.7.1.0, + primitive-extras ==0.10.1, + primitive-sort ==0.1.0.0, + primitive-unlifted ==0.1.3.0, + proto3-wire ==1.2.2, + quickcheck-instances ==0.3.25.2, + random ==1.2.0, + row-types ==1.0.1.0, + safe ==0.3.19, + safecopy ==0.10.4.2, + salak ==0.3.6, + semialign ==1.2, + semigroupoids ==5.3.5, + serialise ==0.2.3.0, + servant ==0.18.2, + shake ==0.19.4, + shakespeare ==2.0.25, + singletons ==2.7 || ==3.0, + singletons-base ==3.0, + siphash ==1.0.3, + streaming-bytestring ==0.2.0, + streaming-commons ==0.2.2.1, + subcategories ==0.1.1.0, + tasty ==1.4.1, + test-framework ==0.8.2.0, + text-format ==0.3.2, + text-short ==0.1.3, + text-show ==3.9, + th-desugar ==1.11 || ==1.12, + tls ==1.5.5, + tpdb ==2.2.0, + tree-diff ==0.2, + true-name ==0.1.0.3, + uniplate ==1.6.13, + vector-builder ==0.3.8.1, + vector-circular ==0.1.3, + vector-th-unbox ==0.2.1.9, + vinyl ==0.13.3, + wai-extra ==3.1.6, + wai-middleware-static ==0.9.0, + warp ==3.3.15, + winery ==1.3.2, + witherable ==0.4.1, + x509-validation ==1.6.11, + xlsx ==0.8.3, + xml-hamlet ==0.5.0.1, + yaml ==0.11.5.0, + yesod-core ==1.6.20 diff --git a/doc/common-errors.rst b/doc/common-errors.rst new file mode 100644 index 00000000..9afa4ea7 --- /dev/null +++ b/doc/common-errors.rst @@ -0,0 +1,19 @@ +Common Errors +============= + +``parse error on input ‘-- | xxx’`` +----------------------------------- + +This is probably caused by the ``-- | xxx`` comment not following a declaration. I.e. use ``-- xxx`` instead. See :ref:`top-level-declaration`. + +``parse error on input ‘-- $ xxx’`` +---------------------------------- + +You've probably commented out code like:: + + f x + $ xxx + +``-- $`` is a special syntax for named chunks, see :ref:`named-chunks`. You can fix this by escaping the ``$``:: + + -- \$ xxx diff --git a/doc/index.rst b/doc/index.rst index dc30c45f..f370e42f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -12,6 +12,8 @@ Contents: intro 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>`_. diff --git a/haddock-api/haddock-api.cabal b/haddock-api/haddock-api.cabal index 730f4f5c..8a02f8ba 100644 --- a/haddock-api/haddock-api.cabal +++ b/haddock-api/haddock-api.cabal @@ -1,6 +1,6 @@ cabal-version: 2.0 name: haddock-api -version: 2.24.0 +version: 2.26.0 synopsis: A documentation-generation tool for Haskell libraries description: Haddock is a documentation-generation tool for Haskell libraries @@ -13,7 +13,7 @@ bug-reports: https://github.com/haskell/haddock/issues copyright: (c) Simon Marlow, David Waern category: Documentation build-type: Simple -tested-with: GHC==9.0.* +tested-with: GHC==9.2.* extra-source-files: CHANGES.md @@ -44,7 +44,7 @@ library -- this package typically supports only single major versions build-depends: base ^>= 4.16.0 - , ghc ^>= 9.1 + , ghc ^>= 9.2 , ghc-paths ^>= 0.1.0.9 , haddock-library ^>= 1.9.0 , xhtml ^>= 3000.2.2 @@ -175,11 +175,11 @@ test-suite spec Haddock.Backends.Hyperlinker.Parser Haddock.Backends.Hyperlinker.Types - build-depends: ghc ^>= 9.1 + build-depends: ghc ^>= 9.2 , ghc-paths ^>= 0.1.0.12 , haddock-library ^>= 1.9.0 , xhtml ^>= 3000.2.2 - , hspec >= 2.4.4 && < 2.8 + , hspec ^>= 2.8 , QuickCheck >= 2.11 && ^>= 2.14 -- Versions for the dependencies below are transitively pinned by @@ -195,10 +195,11 @@ test-suite spec , filepath , ghc-boot , ghc-boot-th + , mtl , transformers build-tool-depends: - hspec-discover:hspec-discover >= 2.4.4 && < 2.8 + hspec-discover:hspec-discover ^>= 2.8 source-repository head type: git diff --git a/haddock-library/haddock-library.cabal b/haddock-library/haddock-library.cabal index 490dff10..74446bf7 100644 --- a/haddock-library/haddock-library.cabal +++ b/haddock-library/haddock-library.cabal @@ -28,6 +28,7 @@ tested-with: GHC == 7.4.2 , GHC == 8.8.3 , GHC == 8.10.1 , GHC == 9.0.1 + , GHC == 9.2.0 extra-source-files: CHANGES.md @@ -39,7 +40,7 @@ common lib-defaults build-depends: , base >= 4.5 && < 4.17 - , bytestring ^>= 0.9.2.1 || ^>= 0.10.0.0 + , bytestring ^>= 0.9.2.1 || ^>= 0.10.0.0 || ^>= 0.11.1.0 , containers ^>= 0.4.2.1 || ^>= 0.5.0.0 || ^>= 0.6.0.1 , transformers ^>= 0.3.0.0 || ^>= 0.4.1.0 || ^>= 0.5.0.0 , text ^>= 1.2.3.0 @@ -96,10 +97,10 @@ test-suite spec -- version of `hspec` & `hspec-discover` to ensure -- intercompatibility build-depends: - , hspec >= 2.4.4 && < 2.8 + , hspec >= 2.4.4 && < 2.9 build-tool-depends: - , hspec-discover:hspec-discover >= 2.4.4 && < 2.8 + , hspec-discover:hspec-discover >= 2.4.4 && < 2.9 test-suite fixtures type: exitcode-stdio-1.0 @@ -118,7 +119,7 @@ test-suite fixtures , directory ^>= 1.3.0.2 , filepath ^>= 1.4.1.2 , optparse-applicative ^>= 0.15 - , tree-diff ^>= 0.1 + , tree-diff ^>= 0.2 source-repository head type: git diff --git a/haddock-test/src/Test/Haddock/Config.hs b/haddock-test/src/Test/Haddock/Config.hs index e4829588..2905dc8f 100644 --- a/haddock-test/src/Test/Haddock/Config.hs +++ b/haddock-test/src/Test/Haddock/Config.hs @@ -18,7 +18,7 @@ import Data.Maybe import Distribution.Text import Distribution.Types.PackageName import Distribution.InstalledPackageInfo -import Distribution.Simple.Compiler +import Distribution.Simple.Compiler (PackageDB(..)) import Distribution.Simple.GHC import Distribution.Simple.PackageIndex import Distribution.Simple.Program diff --git a/haddock.cabal b/haddock.cabal index 215ed0ce..0f98be49 100644 --- a/haddock.cabal +++ b/haddock.cabal @@ -1,6 +1,6 @@ cabal-version: 2.4 name: haddock -version: 2.24.0 +version: 2.26.0 synopsis: A documentation-generation tool for Haskell libraries description: This is Haddock, a tool for automatically generating documentation @@ -33,7 +33,7 @@ bug-reports: https://github.com/haskell/haddock/issues copyright: (c) Simon Marlow, David Waern category: Documentation build-type: Simple -tested-with: GHC==9.0.* +tested-with: GHC==9.2.* extra-source-files: CHANGES.md @@ -146,7 +146,7 @@ executable haddock else -- in order for haddock's advertised version number to have proper meaning, -- we pin down to a single haddock-api version. - build-depends: haddock-api == 2.24.0 + build-depends: haddock-api == 2.26.0 test-suite html-test type: exitcode-stdio-1.0 |