Documentation/mock imports (#785)

* RTD with Mock Imports * Issue with Deprecated Decorator Fixed * Changelog updated + YAPF cleaning * Update .readthedocs.yml * TF 1.6.0 Errors fixed * YAPF Cleaning * TL init if protected * Error fix - Test Documentation
tensorlayer · Aug 14, 2018 · 0156da0 · 0156da0
1 parent 490c44e
commit 0156da0
Show file tree

Hide file tree

Showing 11 changed files with 226 additions and 101 deletions.
diff --git a/.gitignore b/.gitignore
@@ -66,6 +66,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/test_build/
 
 # PyBuilder
 target/
@@ -125,3 +126,4 @@ update_tl.py
 # Data Files and ByteCode files
 *.gz
 *.npz
+venv_doc/
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -9,6 +9,6 @@ formats:
 
 python:
     version: 3.6
-    # to build customized extension, we have to use setup_py_install instead of pip_install
-    # https://docs.readthedocs.io/en/latest/yaml-config.html#python-setup-py-install
-    setup_py_install: true
+
+requirements_file: 
+    requirements/requirements_doc.txt
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -101,7 +101,8 @@ To release a new version, please update the changelog as followed:
   - all the input scale in both vgg16 and vgg19 has been changed the input scale from [0,255] to [0,1](PR #710)
   - Dockerfiles merged and refactored into one file (PR #747)
   - LazyImports move to the most **top level** imports as possible (PR #739)
-  - some new test functions have been added in `test_layers_convolution.py`, `test_layers_normalization.py`, `test_layers_core.py` (PR #735)  
+  - some new test functions have been added in `test_layers_convolution.py`, `test_layers_normalization.py`, `test_layers_core.py` (PR #735)
+  - documentation now uses mock imports reducing the number of dependencies to compile the documentation (PR #785)
 
 ### Deprecated
   - `tl.logging.warn` has been deprecated in favor of `tl.logging.warning` (PR #739)

diff --git a/docs/conf.py b/docs/conf.py
@@ -17,11 +17,12 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-import os, sys
+import os, sys, datetime
 sys.path.insert(0, os.path.abspath("../"))  # Important
+sys.path.insert(0, os.path.abspath(os.path.join("..", "tensorlayer"))) # Important
 
-from tensorlayer import __shortversion__
-from tensorlayer import __version__
+from package_info import __shortversion__
+from package_info import __version__
 
 # -- General configuration ------------------------------------------------
 
@@ -32,17 +33,46 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
+
 # extensions = [
-#    'sphinx.ext.doctest',
 #    'sphinx.ext.coverage',
-#    'sphinx.ext.mathjax',
-#    'sphinx.ext.viewcode',
 #    'sphinx.ext.githubpages',
-#    'sphinx.ext.autosummary',
-#    'sphinx.ext.autodoc',
 #    'numpydoc',
 # ]
 
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.doctest',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.inheritance_diagram',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+]
+
+autodoc_mock_imports = [
+    'cv2',
+    'gridfs',
+    'horovod',
+    'hyperdash',
+    'imageio',
+    'lxml',
+    'matplotlib',
+    'nltk',
+    'numpy',
+    'PIL',
+    'progressbar',
+    'pymongo',
+    'scipy',
+    'skimage',
+    'sklearn',
+    'tensorflow',
+    'tqdm',
+]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -61,7 +91,7 @@
 
 # General information about the project.
 project = 'TensorLayer'
-copyright = '2016~2018, TensorLayer Contributors'
+copyright = '2016~%s, TensorLayer Contributors' % (str(datetime.datetime.now().year))
 author = 'TensorLayer Contributors'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -427,17 +457,6 @@
 # If false, no index is generated.
 #
 # epub_use_index = True
-
-extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.doctest',
-              'sphinx.ext.intersphinx',
-              'sphinx.ext.todo',
-              'sphinx.ext.ifconfig',
-              'sphinx.ext.viewcode',
-              'sphinx.ext.mathjax',
-              'sphinx.ext.inheritance_diagram',
-              'sphinx.ext.autosummary',
-              'sphinx.ext.napoleon']
 
 pygments_style = 'sphinx'
 

diff --git a/requirements/requirements_doc.txt b/requirements/requirements_doc.txt
@@ -1,4 +1,4 @@
 flake8-docstrings>=1.3,<1.4
-matplotlib>=2.2,<2.3
 sphinx>=1.7,<1.8
 sphinx_rtd_theme>=0.4,<0.5
+wrapt>=1.10,<1.11
diff --git a/tensorlayer/__init__.py b/tensorlayer/__init__.py
@@ -7,6 +7,20 @@
 import os
 from distutils.version import LooseVersion
 
+from tensorlayer.package_info import VERSION
+from tensorlayer.package_info import __shortversion__
+from tensorlayer.package_info import __version__
+
+from tensorlayer.package_info import __package_name__
+from tensorlayer.package_info import __contact_names__
+from tensorlayer.package_info import __contact_emails__
+from tensorlayer.package_info import __homepage__
+from tensorlayer.package_info import __repository_url__
+from tensorlayer.package_info import __download_url__
+from tensorlayer.package_info import __description__
+from tensorlayer.package_info import __license__
+from tensorlayer.package_info import __keywords__
+
 if 'TENSORLAYER_PACKAGE_BUILDING' not in os.environ:
 
     try:
@@ -18,16 +32,15 @@
             " - `pip install --upgrade tensorflow-gpu`"
         )
 
-    if LooseVersion(tensorflow.__version__) < LooseVersion("1.6.0") and os.environ.get('READTHEDOCS', None) != 'True':
+    if ("SPHINXBUILD" not in os.environ and "READTHEDOCS" not in os.environ and
+            LooseVersion(tensorflow.__version__) < LooseVersion("1.6.0")):
         raise RuntimeError(
             "TensorLayer does not support Tensorflow version older than 1.6.0.\n"
             "Please update Tensorflow with:\n"
             " - `pip install --upgrade tensorflow`\n"
             " - `pip install --upgrade tensorflow-gpu`"
         )
 
-    from tensorlayer.lazy_imports import LazyImport
-
     from tensorlayer import activation
     from tensorlayer import array_ops
     from tensorlayer import cost
@@ -42,6 +55,8 @@
     from tensorlayer import optimizers
     from tensorlayer import rein
 
+    from tensorlayer.lazy_imports import LazyImport
+
     # Lazy Imports
     db = LazyImport("tensorlayer.db")
     distributed = LazyImport("tensorlayer.distributed")
@@ -60,19 +75,3 @@
     # global vars
     global_flag = {}
     global_dict = {}
-
-# Use the following formatting: (major, minor, patch, prerelease)
-VERSION = (1, 9, 1, "")
-__shortversion__ = '.'.join(map(str, VERSION[:3]))
-__version__ = '.'.join(map(str, VERSION[:3])) + "".join(VERSION[3:])
-
-__package_name__ = 'tensorlayer'
-__contact_names__ = 'TensorLayer Contributors'
-__contact_emails__ = '[email protected]'
-__homepage__ = 'http://tensorlayer.readthedocs.io/en/latest/'
-__repository_url__ = 'https://github.com/tensorlayer/tensorlayer'
-__download_url__ = 'https://github.com/tensorlayer/tensorlayer'
-__description__ = 'Reinforcement Learning and Deep Learning Library for Researcher and Engineer.'
-__license__ = 'apache'
-__keywords__ = 'deep learning, machine learning, computer vision, nlp, '
-__keywords__ += 'supervised learning, unsupervised learning, reinforcement learning, tensorflow'
diff --git a/tensorlayer/decorators/deprecated.py b/tensorlayer/decorators/deprecated.py
@@ -5,9 +5,9 @@
 import sys
 import functools
 
-from tensorflow.python.util import decorator_utils
-
-from tensorflow.python.util.deprecation import _validate_deprecation_args
+from tensorlayer.decorators.utils import add_deprecation_notice_to_docstring
+from tensorlayer.decorators.utils import get_qualified_name
+from tensorlayer.decorators.utils import validate_deprecation_args
 
 import wrapt
 
@@ -20,62 +20,19 @@
 _PRINTED_WARNING = {}
 
 
-def add_notice_to_docstring(doc, no_doc_str, notice):
-    """Adds a deprecation notice to a docstring."""
-    if not doc:
-        lines = [no_doc_str]
-
-    else:
-        lines = decorator_utils._normalize_docstring(doc).splitlines()
-
-    notice = [''] + notice
-
-    if len(lines) > 1:
-        # Make sure that we keep our distance from the main body
-        if lines[1].strip():
-            notice.append('')
-
-        lines[1:1] = notice
-    else:
-        lines += notice
-
-    return '\n'.join(lines)
-
-
-def _add_deprecated_function_notice_to_docstring(doc, date, instructions):
-    """Adds a deprecation notice to a docstring for deprecated functions."""
-
-    if instructions:
-        deprecation_message = """
-            .. warning::
-                **THIS FUNCTION IS DEPRECATED:** It will be removed after %s.
-                *Instructions for updating:* %s.
-        """ % (('in a future version' if date is None else ('after %s' % date)), instructions)
-
-    else:
-        deprecation_message = """
-            .. warning::
-                **THIS FUNCTION IS DEPRECATED:** It will be removed after %s.
-        """ % (('in a future version' if date is None else ('after %s' % date)))
-
-    main_text = [deprecation_message]
-
-    return add_notice_to_docstring(doc, 'DEPRECATED FUNCTION', main_text)
-
-
 def deprecated(wrapped=None, date='', instructions='', warn_once=True):
 
     if wrapped is None:
         return functools.partial(deprecated, date=date, instructions=instructions, warn_once=warn_once)
 
     @wrapt.decorator
-    def deprecated_wrapper(wrapped, instance, args, kwargs):
+    def wrapper(wrapped, instance=None, args=None, kwargs=None):
 
-        _validate_deprecation_args(date, instructions)
+        validate_deprecation_args(date, instructions)
 
         if _PRINT_DEPRECATION_WARNINGS:
 
-            class_or_func_name = decorator_utils.get_qualified_name(wrapped)
+            class_or_func_name = get_qualified_name(wrapped)
 
             if class_or_func_name not in _PRINTED_WARNING:
                 if warn_once:
@@ -94,11 +51,11 @@ def deprecated_wrapper(wrapped, instance, args, kwargs):
 
         return wrapped(*args, **kwargs)
 
-    decorated = deprecated_wrapper(wrapped)
+    decorated = wrapper(wrapped)
 
-    if (sys.version_info > (3, 0)):  # docstring can only be edited with Python 3
+    if sys.version_info > (3, 0):  # docstring can only be edited with Python 3
         wrapt.FunctionWrapper.__setattr__(
-            decorated, "__doc__", _add_deprecated_function_notice_to_docstring(wrapped.__doc__, date, instructions)
+            decorated, "__doc__", add_deprecation_notice_to_docstring(wrapped.__doc__, date, instructions)
         )
 
     return decorated