From 31a8d9e25cea700fa04e77ddc8a605b5889d332d Mon Sep 17 00:00:00 2001
From: Anton Joubert <ajoubert@ska.ac.za>
Date: Thu, 24 Dec 2020 01:12:28 +0200
Subject: [PATCH] Fix doc build issue with ExtractAs

RTD build was failing due to problems with the
`ExtractAs` class.  Now mocking it.  Possibly
a newer version of Sphinx has pointed out this
old problem.

Added a note on how to do a local doc build
using a Docker container.
---
 doc/how-to-contribute.rst   | 10 +++++++++-
 doc/mock_tango_extension.py | 16 ++++++++++++++++
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/doc/how-to-contribute.rst b/doc/how-to-contribute.rst
index 1694b3d5..1b6f4d80 100644
--- a/doc/how-to-contribute.rst
+++ b/doc/how-to-contribute.rst
@@ -30,9 +30,17 @@ It also uses autodoc_ importing docstrings from tango package.
 Theme is not important, a theme prepared for Tango Community can be also used.
 
 To test the docs locally requires Python >= 3.5:
-      - ``$ pip install sphinx sphinx_rtd_theme``
+      - ``$ python -m pip install sphinx sphinx_rtd_theme``
       - ``$ python setup.py build_doc``
 
+To test the docs locally in a Sphinx Docker container:
+      - ``(host) $ cd /path/to/pytango``
+      - ``(host) $ docker run --rm -ti -v $PWD:/docs sphinxdoc/sphinx bash``
+      - ``(container) $ python -m pip install six numpy sphinx_rtd_theme``
+      - ``(container) $ python -m sphinx doc build/sphinx``
+
+After building, open the ``build/doc/index.html`` page in your browser.
+
 Source code standard
 --------------------
 
diff --git a/doc/mock_tango_extension.py b/doc/mock_tango_extension.py
index 6197d2b9..dfa1772f 100644
--- a/doc/mock_tango_extension.py
+++ b/doc/mock_tango_extension.py
@@ -115,12 +115,28 @@ def set_device_proxy_implementations(module):
     module.DeviceProxy = type('DeviceProxy', (module.Connection,), attrs)
 
 
+# Create ExtractAs with dummy "methods"
+def set_extract_as_implementation(module):
+    attrs= {
+        '__module__': module.__name__,
+        'ByteArray': None,
+        'Bytes': None,
+        'List': None,
+        'Nothing': None,
+        'Numpy': None,
+        'String': None,
+        'Tuple': None,
+    }
+    module.ExtractAs = type('ExtractAs', (object,), attrs)
+
+
 # Patch the extension module
 _tango = ExtensionMock(name='_tango')
 _tango.constants.TgLibVers = TANGO_VERSION
 _tango._get_tango_lib_release.return_value = TANGO_VERSION_INT
 set_device_implementations(_tango)
 set_device_proxy_implementations(_tango)
+set_extract_as_implementation(_tango)
 
 
 # Patch modules