Skip to content
This repository was archived by the owner on Aug 3, 2024. It is now read-only.

Add support for custom section anchors #1179

Merged
merged 3 commits into from
Apr 25, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions doc/markup.rst
Original file line number Diff line number Diff line change
Expand Up @@ -508,6 +508,19 @@ on, where the number of ``*``\ s indicates the level of the heading
If you use section headings, then Haddock will generate a table of
contents at the top of the module documentation for you.

By default, when generating HTML documentation Haddock will create an
anchor to each section of the form ``#g:n``, where ``n`` is an integer
that might change as you add new section headings. If you want to
create stable links, you can add an explicit anchor (see
:ref:`anchors`) after the section heading: ::

module Foo (
-- * Classes #classes#
C(..)
) where

This will create an HTML anchor ``#g:classes`` to the section.

The alternative style of placing the commas at the beginning of each
line is also supported. e.g.: ::

Expand Down Expand Up @@ -1150,6 +1163,8 @@ Inspired by reSTs grid tables Haddock supports a complete table representation v
-- | body row 4 | | \] |
-- +------------------------+------------+---------------------+

.. _anchors:

Anchors
~~~~~~~

Expand Down
8 changes: 7 additions & 1 deletion haddock-api/src/Haddock/Backends/Xhtml.hs
Original file line number Diff line number Diff line change
Expand Up @@ -672,10 +672,16 @@ numberSectionHeadings = go 1
where go :: Int -> [ExportItem DocNameI] -> [ExportItem DocNameI]
go _ [] = []
go n (ExportGroup lev _ doc : es)
= ExportGroup lev (show n) doc : go (n+1) es
= case collectAnchors doc of
[] -> ExportGroup lev (show n) doc : go (n+1) es
(a:_) -> ExportGroup lev a doc : go (n+1) es
go n (other:es)
= other : go n es

collectAnchors :: DocH (Wrap (ModuleName, OccName)) (Wrap DocName) -> [String]
collectAnchors (DocAppend a b) = collectAnchors a ++ collectAnchors b
collectAnchors (DocAName a) = [a]
collectAnchors _ = []

processExport :: Bool -> LinksInfo -> Bool -> Maybe Package -> Qualification
-> ExportItem DocNameI -> Maybe Html
Expand Down
91 changes: 91 additions & 0 deletions html-test/ref/SectionLabels.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
><head
><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"
/><meta name="viewport" content="width=device-width, initial-scale=1"
/><title
>SectionLabels</title
><link href="#" rel="stylesheet" type="text/css" title="Linuwial"
/><link rel="stylesheet" type="text/css" href="#"
/><link rel="stylesheet" type="text/css" href="#"
/><script src="haddock-bundle.min.js" async="async" type="text/javascript"
></script
><script type="text/x-mathjax-config"
>MathJax.Hub.Config({ tex2jax: { processClass: "mathjax", ignoreClass: ".*" } });</script
><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"
></script
></head
><body
><div id="package-header"
><span class="caption empty"
>&nbsp;</span
><ul class="links" id="page-menu"
><li
><a href="#"
>Contents</a
></li
><li
><a href="#"
>Index</a
></li
></ul
></div
><div id="content"
><div id="module-header"
><table class="info"
><tr
><th
>Safe Haskell</th
><td
>Safe-Inferred</td
></tr
></table
><p class="caption"
>SectionLabels</p
></div
><div id="table-of-contents"
><div id="contents-list"
><p class="caption" onclick="window.scrollTo(0,0)"
>Contents</p
><ul
><li
><a href="#"
>Section heading</a
></li
></ul
></div
></div
><div id="synopsis"
><details id="syn"
><summary
>Synopsis</summary
><ul class="details-toggle" data-details-id="syn"
><li class="src short"
><a href="#"
>n</a
> :: <a href="#" title="Data.Int"
>Int</a
></li
></ul
></details
></div
><div id="interface"
><a href="#" id="g:custom"
><h1
>Section heading</h1
></a
><div class="top"
><p class="src"
><a id="v:n" class="def"
>n</a
> :: <a href="#" title="Data.Int"
>Int</a
> <a href="#" class="selflink"
>#</a
></p
></div
></div
></div
></body
></html
>
8 changes: 8 additions & 0 deletions html-test/src/SectionLabels.hs
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
module SectionLabels
(
-- * Section heading#custom#
n
) where

n :: Int
n = 3