| Commit message (Collapse) | Author | Age | Files | Lines |
|---|
| |
|
|
| |
Sphinx was complaining about too-short title underlines.
|
| | |
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
* Catch Markdown links at beginning of line within paragraph
Per Issue #774, Markdown links were being parsed as ordinary text when
they occurred at the beginning of a line other than the first line of
the paragraph. This occurred because the parser was not interpreting a
left square bracket as a special character that could delimit special
markup. A space character was considered a special character, so, if a
space occurred at the beginning of the new line, then the parser would
interpret the space by itself and then continue parsing, thereby
catching the Markdown link. '\n' was not treated as a special character,
so the parser did not catch a Markdown link that may have followed.
Note that this will allow for Markdown links that are not surrounded by
spaces. For example, the following text includes a Markdown link that
will be parsed:
Hello, world[label](url)
This is consistent with how the parser handles other types of markup.
* Remove obsolete documentation hint
Commit 6b9aeafddf20efc65d3725c16e3fc43a20aac343 should eliminate the
need for the workaround suggested in the documentation.
|
| | |
|
| | |
|
| |
|
|
|
|
|
|
|
|
| |
Support a markdown-style way of annotating module references. For instance
-- | [label]("Module.Name#anchor")
will create a link that points to the same place as the module
reference "Module.Name#anchor" but the text displayed on the link will
be "label".
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
* Fix multiple typos and inconsistencies in doc/markup.rst
Note: I noticed some overlap with #1112 from @wygulmage and #1081 from
@parsonsmatt after creating these proposed changes - mea culpa for not
looking at the open PRs sooner.
* Fix #1113 If no Signatures, no section of index.html
* Change the formatting of missing link destinations
The current formatting of the missing link destination does not really
help user to understand the reasons of the missing link.
To address this, I've changed the formatting in two ways:
- the missing link symbol name is now fully qualified. This way you
immediately know which haskell module cannot be linked. It is then easier
to understand why this module does not have documentation (hidden module
or broken documentation).
- one line per missing link, that's more readable now that symbol name
can be longer due to qualification.
For example, before haddock was listing missing symbol such as:
```
could not find link destinations for:
Word8 Word16 mapMaybe
```
Now it is listed as:
```
could not find link destinations for:
- Data.Word.Word8
- Data.Word.Word16
- Data.Maybe.mapMaybe
```
* Add `--ignore-link-symbol` command line argument
This argument can be used multiples time. A missing link to a symbol
listed by `--ignore-link-symbol` won't trigger "missing link" warning.
* Forbid spaces in anchors (#1148)
* Improve error messages with context information (#1060)
Co-authored-by: Matt Audesse <matt@mattaudesse.com>
Co-authored-by: Mike Pilgrem <mpilgrem@users.noreply.github.com>
Co-authored-by: Guillaume Bouchard <guillaume.bouchard@tweag.io>
Co-authored-by: Pepe Iborra <pepeiborra@gmail.com>
|
| | |
|
| |
|
|
|
|
|
|
|
|
|
|
| |
This allows to have stable anchors for groups, even if the set of
groups in the documentation is altered.
The syntax for setting the anchor of a group is
-- * Group name #desiredAnchor#
Which will produce an html anchor of the form '#g:desiredAnchor'
Co-authored-by: Iñaki García Etxebarria <git@inaki.blueleaf.cc>
|
| |\ |
|
| | |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| | |
* '(<|>)' and '`elem`' now get parsed and rendered properly as links
* 'DbModule'/'DbUnitId' now properly get split apart into two links
* tuple names now get parsed properly
* some more small niceties...
The identifier parsing code is more precise and more efficient (although to be
fair: it is also longer and in its own module). On the rendering side, we need
to pipe through information about backticks/parens/neither all the way through
from renaming to the backends.
In terms of impact: a total of 35 modules in the entirety of the bootlib + ghc
lib docs change. The only "regression" is things like '\0'. These should be
changed to @\\0@ (the path by which this previously worked seems accidental).
|
| | |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| | |
Identifier links can be prefixed with a 'v' or 't' to indicate the value or
type namespace of the desired identifier. For example:
-- | Some link to a value: v'Data.Functor.Identity'
--
-- Some link to a type: t'Data.Functor.Identity'
The default is still the type (with a warning about the ambiguity)
|
| |/ |
|
| |\
| |
| | |
Fix & add to documentation
|
| | |
| |
| |
| |
| |
| |
| |
| | |
* Add documentation for a bunch of previously undocumented
options (fixes #870)
* Extend the documentation of `--hoogle` considerably (see #807)
* Describe how to add docs to `deriving` clauses (fixes #912)
* Fix inaccurate docs about hyperlinking infix identifiers (fixes #780)
|
| | |
| |
| |
| |
| |
| |
| |
| | |
* Add tests for the identifier parser
* docs: Clarify how to delimit identifiers
(cherry picked from commit 0861affeca4d72938f05a2eceddfae2c19199071)
|
| |\ \ |
|
| | | |
| | |
| | |
| | |
| | |
| | |
| | | |
On
https://haskell-haddock.readthedocs.io/en/latest/markup.html#special-characters
the backslash and backtick special characters showed up with an extra
backslash before them – I think the escaping is not (or no longer)
needed for those characters in rst.
|
| | | |
| | |
| | |
| | | |
'#' has special meaning used for anchors and can be escaped using backslash.
Therefore it would be nice to be listed as special characters.
|
| | | |
| | |
| | |
| | |
| | |
| | | |
* Add tests for the identifier parser
* docs: Clarify how to delimit identifiers
|
| | |/
|/|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| | |
* Revert "Bump GHC version to 8.6"
This was applied to the wrong branch; there's now a `ghc-8.6` branch;
ghc-head is always supposed to point to GHC HEAD, i.e. an odd major version.
The next version bump to `ghc-head` is supposed to go from e.g. 8.5 to 8.7
This reverts commit 5e3cf5d8868323079ff5494a8225b0467404a5d1.
* README updates (#856)
* README: Remove mentions of master branch
* README: Add instructions for using html-test
* README: Change command to run _all_ the testsuites
* README: Add project overview section
(cherry picked from commit 61d6f935da97eb96685f07bf385102c2dbc2a33c)
* Export more fixities for Hoogle (#871)
This exports fixities for more things, including class methods and
type-level operators.
(cherry picked from commit 88316b972e3d47197b1019111bae0f7f87275fce)
* Avoid line breaks due to line length in Hoogle (#868)
* Avoid line breaks due to line length in Hoogle
Hoogle operates in a line-oriented fashion, so we should avoid ever
breaking due to long lines.
One way of doing this non-intrusively is to modify the 'DynFlags' that
are threaded through the 'Hoogle' module (note this is anyways only
passed through for use in the various 'showSDoc' functions).
* Amend test case
(cherry picked from commit 657b1b3d519545f8d4ca048c06210d6cbf0f0da0)
* tyThingToLHsDecl: Preserve type synonyms that contain a forall (#880)
* tyThingToLHsDecls: Preserve type synonyms that contain a forall
Fixes #879.
* Add Note [Invariant: Never expand type synonyms]
* Clarify Note [Invariant: Never expand type synonyms]
(cherry picked from commit c3eb3f0581f69e816f9453b1747a9f2a3ba02bb9)
* Fix HEAD html-test (#860)
* Update tests for 'StarIsType'
* Accept tests
* Revert "Update tests for 'StarIsType'"
This reverts commit 7f0c01383bbba6dc5af554ee82988d2cf44e407a.
* Refactor handling of parens in types (#874)
* Fix type parenthesization in Hoogle backend
Ported the logic in the HTML and LaTeX backends for adding in parens
into something top-level in 'GhcUtil'. Calling that from the Hoogle
backend fixes #873.
* Remove parenthesizing logic from LaTeX and XHTML backends
Now, the only times that parenthesis in types are added in any backend
is through the explicit 'HsParTy' constructor. Precedence is also
represented as its own datatype.
* List out cases explicitly vs. catch-all
* Fix printing of parens for QuantifiedConstraints
The priority of printing 'forall' types was just one too high.
Fixes #877.
* Accept HTML output for quantified contexts test
* Preserve docs on type family instances (#867)
* Preserve docs on type family instances
The only problem was that the instance location was slightly off
for type family instances.
* Accept output
(cherry picked from commit 133e9c2c168db19c1135479f7ab144c4e33af2a4)
* Fix broken instance source links (#869)
The problem manifests itself in instances that are defined in
modules other than the module where the class is defined. The fix
is just to thread through the 'Module' of the instance further
along.
Since orphan instances appear to already have been working, I didn't
do anything there.
(cherry picked from commit 2de7c2acf9b1ec85b09027a8bb58bf8512e91c05)
* Add some more unicode related tests (#872)
This has been fixed for sure ever since we switched from attoparsec to
parsec. Parts of it may have been working before that, but there was a
point where this would have failed (see #191).
A regression test never hurt anyone. :)
(cherry picked from commit 5ec7715d418bfac0f26aec6039792a99a6e89370)
* Misc tests (#858)
* More tests
* spliced types
* constructor/pattern argument docs
* strictness marks on fields with argument docs
* latex test cases need seperate directory
* Accept tests
* Additional tests for the identifier parser (#816)
* Add tests for the identifier parser
* docs: Clarify how to delimit identifiers
(cherry picked from commit 0861affeca4d72938f05a2eceddfae2c19199071)
|
| |\ \
| |/
|/| |
|
| | |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| | |
* Support Haddocks on constructor arguments
This is in conjunction with https://phabricator.haskell.org/D4094.
Adds support for rendering Haddock's on (non-record) constructor
arguments, both for regular and GADT constructors.
* Support haddocks on pattern synonym arguments
It appears that GHC already parsed these - we just weren't using them.
In the process of doing this, I tried to deduplicate some code around
handling patterns.
* Update the markup guide
Add some information about the new support for commenting constructor
arguments, and mention pattern synonyms and GADT-style constructors.
* Overhaul LaTeX support for data/pattern decls
This includes at least
* fixing several bugs that resulted in invalid LaTeX
* fixing GADT data declaration headers
* overhaul handling of record fields
* overhaul handling of GADT constructors
* overhaul handling of bundled patterns
* add support for constructor argument docs
* Support GADT record constructors
This means changes what existing HTML docs look like.
As for LaTeX, looks like GADT records were never even supported. Now they are.
* Clean up code/comments
Made code/comments consistent between the LaTeX and XHTML backend
when possible.
* Update changelog
* Patch post-rebase regressions
* Another post-rebase change
We want return values to be documentable on record GADT constructors.
|
| |/
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
* Add table examples
* Add table types and adopt simple parser
Simple parser is done by Giovanni Cappellotto (@potomak)
in https://github.com/haskell/haddock/pull/577
It seems to support single fine full tables, so far from full
RST-grid tables, but it's good start.
Table type support row- and colspans, but obviously parser is lacking.
Still TODO:
- Latex backend. Should we use multirow package
https://ctan.org/pkg/multirow?lang=en?
- Hoogle backend: ?
* Implement grid-tables
* Refactor table parser
* Add two ill-examples
* Update CHANGES.md
* Basic documentation for tables
* Fix documentation example
|
| |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
* Improve documentation of Haddock markup.
- document that Haddock supports inferring types top-level functions
with without type signatures, but also explain why using this
feature is discouraged. Looks like this feature has been around
since version 2.0.0.0 in 2008!
- rework the "Module description" section:
- move the general discussion of field formatting to the section
intro and add examples illustrating the prose for multiline
fields.
- mention that newlines are preserved in some multiline fields, but
not in others (I also noticed that commas in the `Copyright` field
are not preserved; I'll look into this bug later).
- add a subsection for the module description fields documentation,
and put the field keywords in code formatting (double back ticks)
instead of double quotes, to be consistent with the typesetting of
keywords in other parts of the documentation.
- mention that "Named chunks" are not supported in the long-form
"Module description" documentation.
- fix formatting of keywords in the "Module attributes"
section. Perhaps these errors were left over from an automatic
translation to ReST from some other format as part of the transition
to using Sphinx for Haddock documentation? Also, add a missing
reference here; it just said "See ?"!
- update footnote about special treatment for re-exporting partially
imported modules not being implemented. In my tests it's not
implemented at all -- I tried re-exporting both `import B
hiding (f)` and `import B (a, b)` style partial imports, and in both
cases got the same result as with full imports `import B`: I only
get a module reference.
* Rework the `Controlling the documentation structure` section.
My main goal was to better explain how to use Haddock without an
export list, since that's my most common use case, but I hope I
improved the section overall:
- remove the incomplete `Omitting the export list` section and fold it
into the other sections. In particular, summarize the differences
between using and not using an export list -- i.e. control over what
and in what order is documented -- in the section lead.
- add "realistic" examples that use the structure markup, both with
and without an export list. I wanted a realistic example here to
capture how it can be useful to explain the relationship between a
group of functions in a section, in addition to documenting their
individual APIs.
- make it clear that you can associate documentation chunks with
documentation sections when you aren't using an export list, and
that doing it in the most obvious way -- i.e. with `-- |`, as you
can in the export list -- doesn't work without an export list. It
took me a while to figure this out the first time, since the docs
didn't explain it at all before.
- add a "no export list" example to the section header section.
- add more cross references.
* Add examples of gotchas for markup in `@...@`.
I'm not sure this will help anyone, since I think most people first
learn about `@...@` by reading other people's Haddocks, but I've
documented the mistakes which I've made and then gotten confused by.
* Use consistent Capitalization of Titles.
Some titles were in usual title caps, and others only had the first
word capitalized. I chose making them all use title caps because that
seems to make the cross references look better.
|
| |
|
|
|
|
|
|
| |
If this character is not escaped, documentation built with Haddock
2.17.2 will fail. This was not an issue with 2.16 series, which
causes builds to fail and there is nothing in the docs or error
message giving a clue about why builds that used to succeed now
don't.
|
| | |
|
| | |
|
| | |
|
| | |
|
| |
|
