Add support for custom section anchors (#1179)

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>

1 files changed, 15 insertions, 0 deletions

diff --git a/doc/markup.rst b/doc/markup.rst
index 08510804..af71e7c7 100644
--- a/doc/markup.rst
+++ b/doc/markup.rst
@@ -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.: ::
 
@@ -1150,6 +1163,8 @@ Inspired by reSTs grid tables Haddock supports a complete table representation v
     -- | body row 4             |            | \]                  |
     -- +------------------------+------------+---------------------+
 
+.. _anchors:
+
 Anchors
 ~~~~~~~