DOC/BLD: doc building with python 3 (#15012)

* DOC/BLD: only use mpl.use once to prevent warnings

* DOC/BLD: make the custom accessor documenters py3 compat

- give lower priority (eg if both MethodDocumenter and AccessorMethodDocumenter have priority 1, in python 3 one of both is randomly chosen, also for normal methods (because the can_document_member method cannot distinguish both)
- adapt templates (module and objname were differently split between py2 and py3)

* DOC/BLD: add specific AccessorDocumenter to prevent warning 'error while formatting arguments' during doc build

* DOC/BLD: switch travis dev doc building to python 3.5

* fix dateutil specification

* fix beatifulsoup package name for python 3

Author: jorisvandenbossche

.travis.yml

@@ -182,9 +182,9 @@ matrix:
         - CACHE_NAME="35_ascii"
         - USE_CACHE=true
 #    In allow_failures
-    - python: 2.7
+    - python: 3.5
       env:
-        - PYTHON_VERSION=2.7
+        - PYTHON_VERSION=3.5
         - JOB_NAME: "doc_build"
         - FULL_DEPS=true
         - DOC_BUILD=true
@@ -275,9 +275,9 @@ matrix:
         - LOCALE_OVERRIDE="C"
         - CACHE_NAME="35_ascii"
         - USE_CACHE=true
-      - python: 2.7
+      - python: 3.5
         env:
-        - PYTHON_VERSION=2.7
+        - PYTHON_VERSION=3.5
         - JOB_NAME: "doc_build"
         - FULL_DEPS=true
         - DOC_BUILD=true

ci/requirements-2.7_DOC_BUILD.build renamed to ci/requirements-3.5_DOC_BUILD.build

@@ -1,4 +1,4 @@
-dateutil
+python-dateutil
 pytz
 numpy
 cython

ci/requirements-2.7_DOC_BUILD.run renamed to ci/requirements-3.5_DOC_BUILD.run

@@ -7,7 +7,7 @@ notebook
 matplotlib
 scipy
 lxml
-beautiful-soup
+beautifulsoup4
 html5lib
 pytables
 openpyxl=1.8.5

ci/requirements-2.7_DOC_BUILD.sh renamed to ci/requirements-3.5_DOC_BUILD.sh

@@ -3,4 +3,4 @@
 
 .. currentmodule:: {{ module.split('.')[0] }}
 
-.. automethod:: {{ [module.split('.')[1], objname]|join('.') }}
+.. autoaccessor:: {{ (module.split('.')[1:] + [objname]) | join('.') }}

doc/_templates/autosummary/accessor.rst

@@ -3,4 +3,4 @@
 
 .. currentmodule:: {{ module.split('.')[0] }}
 
-.. autoaccessorattribute:: {{ [module.split('.')[1], objname]|join('.') }}
+.. autoaccessorattribute:: {{ (module.split('.')[1:] + [objname]) | join('.') }}

doc/_templates/autosummary/accessor_attribute.rst

@@ -3,4 +3,4 @@
 
 .. currentmodule:: {{ module.split('.')[0] }}
 
-.. autoaccessorcallable:: {{ [module.split('.')[1], objname]|join('.') }}.__call__
+.. autoaccessorcallable:: {{ (module.split('.')[1:] + [objname]) | join('.') }}.__call__

doc/_templates/autosummary/accessor_callable.rst

@@ -3,4 +3,4 @@
 
 .. currentmodule:: {{ module.split('.')[0] }}
 
-.. autoaccessormethod:: {{ [module.split('.')[1], objname]|join('.') }}
+.. autoaccessormethod:: {{ (module.split('.')[1:] + [objname]) | join('.') }}

doc/_templates/autosummary/accessor_method.rst

@@ -326,6 +326,23 @@
 from sphinx.ext.autosummary import Autosummary
 
 
+class AccessorDocumenter(MethodDocumenter):
+    """
+    Specialized Documenter subclass for accessors.
+    """
+
+    objtype = 'accessor'
+    directivetype = 'method'
+
+    # lower than MethodDocumenter so this is not chosen for normal methods
+    priority = 0.6
+
+    def format_signature(self):
+        # this method gives an error/warning for the accessors, therefore
+        # overriding it (accessor has no arguments)
+        return ''
+
+
 class AccessorLevelDocumenter(Documenter):
     """
     Specialized Documenter subclass for objects on accessor level (methods,
@@ -381,12 +398,17 @@ class AccessorAttributeDocumenter(AccessorLevelDocumenter, AttributeDocumenter):
     objtype = 'accessorattribute'
     directivetype = 'attribute'
 
+    # lower than AttributeDocumenter so this is not chosen for normal attributes
+    priority = 0.6
 
 class AccessorMethodDocumenter(AccessorLevelDocumenter, MethodDocumenter):
 
     objtype = 'accessormethod'
     directivetype = 'method'
 
+    # lower than MethodDocumenter so this is not chosen for normal methods
+    priority = 0.6
+
 
 class AccessorCallableDocumenter(AccessorLevelDocumenter, MethodDocumenter):
     """
@@ -483,6 +505,7 @@ def remove_flags_docstring(app, what, name, obj, options, lines):
 
 def setup(app):
     app.connect("autodoc-process-docstring", remove_flags_docstring)
+    app.add_autodocumenter(AccessorDocumenter)
     app.add_autodocumenter(AccessorAttributeDocumenter)
     app.add_autodocumenter(AccessorMethodDocumenter)
     app.add_autodocumenter(AccessorCallableDocumenter)

doc/source/conf.py

@@ -786,7 +786,7 @@ def setup(self):
             # EmbeddedSphinxShell is created, its interactive shell member
             # is the same for each instance.
 
-            if mplbackend:
+            if mplbackend and 'matplotlib.backends' not in sys.modules:
                 import matplotlib
                 # Repeated calls to use() will not hurt us since `mplbackend`
                 # is the same each time.