From 2a55b6e95f51c648dc94bf3c89db7370b56c1c9c Mon Sep 17 00:00:00 2001
From: Long Vu <vu.long@ouranos.ca>
Date: Mon, 27 Jul 2020 18:30:23 -0400
Subject: [PATCH] ext_autodoc: support RST anonymous link

Sphinx "Duplicate explicit target name" warning is problematic when
warning are turned into errors (`sphinx-build -W`).

And we would want warnings to turn into error because autodoc import
failure are treated as warnings only, resulting into silent
documentation build failure if those warnings do not fail the build.

See PR https://github.com/bird-house/cookiecutter-birdhouse/pull/96 with
the silent doc build error.
---
 pywps/ext_autodoc.py | 20 +++++++++++++++++++-
 pywps/tests.py       |  6 +++++-
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/pywps/ext_autodoc.py b/pywps/ext_autodoc.py
index bc960cb83..664847505 100644
--- a/pywps/ext_autodoc.py
+++ b/pywps/ext_autodoc.py
@@ -8,6 +8,21 @@
 from pywps.app.Common import Metadata
 
 
+class MetadataUrl(Metadata):
+    """Metadata subclass to allow anonymous links generation.
+
+    Useful to avoid Sphinx "Duplicate explicit target name" warning.
+
+    See https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#anonymous-hyperlinks.
+    """
+
+    def __init__(self, title, href=None, role=None, type_='simple',
+                 anonymous=False):
+        super().__init__(title, href=href, role=role, type_=type_)
+        self.anonymous = anonymous
+        "Whether to create anonymous link (boolean)."
+
+
 class ProcessDocumenter(ClassDocumenter):
     """Sphinx autodoc ClassDocumenter subclass that understands the
     pywps.Process class.
@@ -126,8 +141,11 @@ class instance.
                 title, href = m['title'], m['href']
             else:
                 title, href = None, None
+            extra_underscore = ""
+            if isinstance(m, MetadataUrl):
+                extra_underscore = "_" if m.anonymous else ""
             if title and href:
-                ref.append(u" - `{} <{}>`_".format(title, href))
+                ref.append(u" - `{} <{}>`_{}".format(title, href, extra_underscore))
                 hasref = True
 
         ref.append('')
diff --git a/pywps/tests.py b/pywps/tests.py
index cafcc6a37..c8d3e84e3 100644
--- a/pywps/tests.py
+++ b/pywps/tests.py
@@ -12,6 +12,7 @@
 from pywps.inout import LiteralInput, LiteralOutput, ComplexInput, ComplexOutput, BoundingBoxInput, BoundingBoxOutput
 from pywps.inout import Format
 from pywps.app.Common import Metadata
+from pywps.ext_autodoc import MetadataUrl
 
 import re
 
@@ -75,7 +76,10 @@ def __init__(self):
             version="4.0",
             metadata=[Metadata('PyWPS docs', 'https://pywps.org'),
                       Metadata('NumPy docstring conventions',
-                               'https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt')],
+                               'https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt'),
+                      MetadataUrl('Duplicate label', 'http://one.example.com', anonymous=True),
+                      MetadataUrl('Duplicate label', 'http://two.example.com', anonymous=True),
+                      ],
             inputs=inputs,
             outputs=outputs,
         )