diff options
| -rw-r--r-- | .github/workflows/ci.yml | 7 | ||||
| -rw-r--r-- | README.md | 10 | ||||
| -rw-r--r-- | doc/common-errors.rst | 19 | ||||
| -rw-r--r-- | doc/index.rst | 1 | ||||
| -rw-r--r-- | doc/intro.rst | 93 | ||||
| -rw-r--r-- | doc/markup.rst | 45 | ||||
| -rw-r--r-- | haddock-api/haddock-api.cabal | 11 | ||||
| -rw-r--r-- | haddock-api/src/Haddock/Backends/Hyperlinker.hs | 1 | ||||
| -rw-r--r-- | haddock-library/haddock-library.cabal | 13 | ||||
| -rw-r--r-- | haddock-test/src/Test/Haddock/Config.hs | 2 | ||||
| -rw-r--r-- | haddock.cabal | 6 |
11 files changed, 102 insertions, 106 deletions
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c2aa9f3c..dafcdc74 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,7 +13,7 @@ jobs: strategy: matrix: os: [ubuntu-latest] - cabal: ["3.4.0.0"] + cabal: ["3.6"] ghc: - "head" @@ -41,12 +41,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: | @@ -2,7 +2,7 @@ Haddock is the standard tool for generating documentation from Haskell code. Full documentation about Haddock itself can be found in the `doc/` subdirectory, -in [reStructedText format][ReST] format. +in [reStructuredText][reST] format. ## Project overview @@ -25,10 +25,10 @@ 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 +[reST]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html [Documentation.Haddock]: http://hackage.haskell.org/package/haddock-api/docs/Documentation-Haddock.html -[cabal v2]: http://cabal.readthedocs.io/en/latest/nix-local-build-overview.html +[cabal v2]: https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html 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 0d1b8b48..f370e42f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -12,6 +12,7 @@ Contents: intro invoking markup + common-errors multi-components diff --git a/doc/intro.rst b/doc/intro.rst index fc1269f9..1f4234cb 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -25,7 +25,7 @@ in mind: The easier it is to write documentation, the more likely the programmer is to do it. Haddock therefore uses lightweight markup in its annotations, taking several ideas from - `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__. In fact, + `IDoc <https://web.archive.org/web/20180621053227/http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__. In fact, Haddock can understand IDoc-annotated source code. - The documentation should not expose any of the structure of the @@ -59,8 +59,8 @@ in mind: Obtaining Haddock ----------------- -Distributions (source & binary) of Haddock can be obtained from its `web -site <http://www.haskell.org/haddock/>`__. +Haddock is distributed with GHC distributions, and will automatically be provided if you use +`ghcup <https://www.haskell.org/ghcup>`__, for instance. Up-to-date sources can also be obtained from our public GitHub repository. The Haddock sources are at @@ -72,77 +72,38 @@ License The following license covers this documentation, and the Haddock source code, except where otherwise indicated. - Copyright 2002-2010, Simon Marlow. All rights reserved. + Copyright (c) 2002-2010, Simon Marlow + All rights reserved. Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: + modification, are permitted provided that the following conditions are + met: - - Redistributions of source code must retain the above copyright + 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - - Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS IS" AND ANY - EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE - LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Contributors ------------ -Haddock was originally written by Simon Marlow. Since it is an open -source project, many people have contributed to its development over the -years. Below is a list of contributors in alphabetical order that we -hope is somewhat complete. If you think you are missing from this list, -please contact us. - -- Ashley Yakeley -- Benjamin Franksen -- Brett Letner -- Clemens Fruhwirth -- Conal Elliott -- David Waern -- Duncan Coutts -- George Pollard -- George Russel -- Hal Daume -- Ian Lynagh -- Isaac Dupree -- Joachim Breitner -- Krasimir Angelov -- Lennart Augustsson -- Luke Plant -- Malcolm Wallace -- Manuel Chakravarty -- Marcin Szamotulski -- Mark Lentczner -- Mark Shields -- Mateusz Kowalczyk -- Mike Thomas -- Neil Mitchell -- Oliver Brown -- Roman Cheplyaka -- Ross Paterson -- Sigbjorn Finne -- Simon Hengel -- Simon Marlow -- Simon Peyton-Jones -- Stefan O'Rear -- Sven Panne -- Thomas Schilling -- Wolfgang Jeltsch -- Yitzchak Gale +A list of contributors to the project can be seen at +``https://github.com/haskell/haddock/graphs/contributors``. Acknowledgements ---------------- @@ -150,11 +111,11 @@ Acknowledgements Several documentation systems provided the inspiration for Haddock, most notably: -- `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__ +- `IDoc <https://web.archive.org/web/20180621053227/http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__ -- `HDoc <http://www.fmi.uni-passau.de/~groessli/hdoc/>`__ +- `HDoc <https://mail.haskell.org/pipermail/haskelldoc/2001-April/000067.html>`__ -- `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`__ +- `Doxygen <https://www.doxygen.nl/index.html>`__ and probably several others I've forgotten. diff --git a/doc/markup.rst b/doc/markup.rst index c0b08a40..abfeb52a 100644 --- a/doc/markup.rst +++ b/doc/markup.rst @@ -950,24 +950,30 @@ apostrophes themselves: to hyperlink ``foo'`` one would simply type -- | A prefix operator @'(++)'@ and an infix identifier @'`elem`'@. -Emphasis, Bold and Monospaced Text +Emphasis, Bold and Monospaced styled Text ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Emphasis may be added by surrounding text with ``/.../``. Other markup -is valid inside emphasis. To have a forward slash inside of emphasis, -just escape it: ``/fo\/o/`` +Text can be emphasized, made bold (strong) or monospaced (typewriter font) +by surrounding it with slashes, double-underscores or at-symbols: :: -Bold (strong) text is indicated by surrounding it with ``__...__``. -Other markup is valid inside bold. For example, ``__/foo/__`` will make -the emphasised text ``foo`` bold. You don't have to escape a single -underscore if you need it bold: -``__This_text_with_underscores_is_bold__``. + -- | This is /emphasized text/, __bold text__ and @monospaced text@. -Monospaced (or typewriter) text is indicated by surrounding it with -``@...@``. Other markup is valid inside a monospaced span: for example -``@'f' a b@`` will hyperlink the identifier ``f`` inside the code -fragment, but ``@__FILE__@`` will render ``FILE`` in bold with no -underscores, which may not be what you had in mind. +Note that those styled texts must be kept on the same line: :: + + -- | Styles /do not work + -- | when continuing on the next line/ + +Other markup is valid inside emphasized, bold and monospaced text. + +Frequent special cases: + +* To have a forward slash inside of emphasis, just escape it: ``/fo\/o/``. +* There's no need to escape a single underscore if you need it + bold: ``__This_text_with_underscores_is_bold__``. +* ``@'f' a b@`` will hyperlink the identifier ``f`` inside the code + fragment. +* ``@__FILE__@`` will render ``FILE`` in bold with no underscores, + which may not be what you had in mind. Linking to Modules ~~~~~~~~~~~~~~~~~~ @@ -1121,6 +1127,17 @@ followed by the URL enclosed in regular parentheses, for example: :: The link text is used as a description for the URL if the output format supports it. +Hint: There's a `known issue <https://github.com/haskell/haddock/issues/774>`_ +that any inline link at the beginning of a line within a multi-line comment +isn't rendered correctly: :: + + {-| Some multi-line comment that has a + [link](https://example.com) and a + [reference link]: https://example.com + -} + +Adding a space or a word in front of such a link can be used as a workaround. + Images ~~~~~~ diff --git a/haddock-api/haddock-api.cabal b/haddock-api/haddock-api.cabal index cd02bf25..9770061c 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 @@ -180,11 +180,11 @@ test-suite spec Haddock.Backends.Hyperlinker.Parser Haddock.Backends.Hyperlinker.Types - build-depends: ghc ^>= 9.1 + build-depends: ghc ^>= 9.3 , ghc-paths ^>= 0.1.0.12 , haddock-library ^>= 1.9.0 , xhtml ^>= 3000.2.2 - , hspec >= 2.4.4 && < 2.8 + , hspec ^>= 2.9 , parsec ^>= 3.1.13.0 , QuickCheck >= 2.11 && ^>= 2.14 @@ -201,10 +201,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.9 source-repository head type: git diff --git a/haddock-api/src/Haddock/Backends/Hyperlinker.hs b/haddock-api/src/Haddock/Backends/Hyperlinker.hs index 68e03fd5..89828e30 100644 --- a/haddock-api/src/Haddock/Backends/Hyperlinker.hs +++ b/haddock-api/src/Haddock/Backends/Hyperlinker.hs @@ -114,4 +114,3 @@ highlightScript = "highlight.js" -- | Path to default CSS file. defaultCssFile :: FilePath -> FilePath defaultCssFile libdir = libdir </> "html" </> "solarized.css" - diff --git a/haddock-library/haddock-library.cabal b/haddock-library/haddock-library.cabal index 72c11f75..f6d88c81 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,10 +40,8 @@ common lib-defaults build-depends: , base >= 4.5 && < 4.17 - , bytestring ^>= 0.9.2.1 || ^>= 0.10.0.0 || ^>= 0.11.0.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 + , text ^>= 1.2.3.0 || ^>= 2.0 , parsec ^>= 3.1.13.0 ghc-options: -funbox-strict-fields -Wall @@ -87,7 +86,7 @@ test-suite spec Documentation.Haddock.Parser.Identifier build-depends: - , QuickCheck ^>= 2.11 || ^>= 2.13.2 || ^>= 2.14 + , QuickCheck ^>= 2.11 || ^>= 2.13.2 || ^>= 2.14 , deepseq ^>= 1.3.0.0 || ^>= 1.4.0.0 -- NB: build-depends & build-tool-depends have independent @@ -95,10 +94,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.10 build-tool-depends: - , hspec-discover:hspec-discover >= 2.4.4 && < 2.8 + , hspec-discover:hspec-discover >= 2.4.4 && < 2.10 test-suite fixtures type: exitcode-stdio-1.0 @@ -116,7 +115,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 dfb4e9a9..0686289e 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 @@ -148,7 +148,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 |