Fix failing docs (#1821)

* missing pkg

* update CI

* strict RTD

* strict RTD

* make

* missing

* ignore

* ignore

* mock

* typo

.circleci/config.yml

@@ -13,7 +13,7 @@ references:
         sudo apt-get update && sudo apt-get install -y cmake
         pip install "$TORCH_VERSION"
         pip install -r requirements.txt -q
-        sudo pip install pytest pytest-cov pytest-flake8 -q
+        sudo pip install pytest -q
         pip install -r ./tests/requirements-devel.txt -q
 
   tests: &tests
@@ -63,14 +63,19 @@ references:
    run:
      name: Make Documentation
      command: |
-       # sudo apt-get install pandoc
+       # First run the same pipeline as Read-The-Docs
        sudo apt-get update && sudo apt-get install -y cmake
-       pip install -r requirements.txt --user
        sudo pip install -r docs/requirements.txt
-       pip install -r requirements-extra.txt --user  # for doctesting loggers etc.
-       # sphinx-apidoc -o ./docs/source ./pytorch_lightning **/test_* --force --follow-links
        cd docs; make clean; make html --debug --jobs 2 SPHINXOPTS="-W"
-       make doctest; make coverage
+
+  test_docs: &test_docs
+   run:
+     name: Testing Documentation
+     command: |
+       # Second run examples in docs
+       sudo apt-get update && sudo apt-get install -y cmake
+       sudo pip install -r docs/requirements.txt
+       cd docs; make doctest; make coverage
 
 jobs:
 
@@ -160,9 +165,11 @@ jobs:
       - image: circleci/python:3.7
     environment:
         - TORCH_VERSION: "torch"
+        - SPHINX_MOCK_REQUIREMENTS: 0
     steps:
       - checkout
       - *install_deps
+      - *test_docs
       - *examples
 
   Install-pkg:

.readthedocs.yml

@@ -6,8 +6,11 @@
 version: 2
 
 # Build documentation in the docs/ directory with Sphinx
+# reference: https://docs.readthedocs.io/en/stable/config-file/v2.html#sphinx
 sphinx:
   configuration: docs/source/conf.py
+  # TODO: set it true and debug failing
+  fail_on_warning: false
 
 # Build documentation with MkDocs
 #mkdocs:

docs/source/conf.py

@@ -29,7 +29,7 @@
 
 builtins.__LIGHTNING_SETUP__ = True
 
-IS_READTHEDOCS_BUILD = os.environ.get('READTHEDOCS', False)
+SPHINX_MOCK_REQUIREMENTS = int(os.environ.get('SPHINX_MOCK_REQUIREMENTS', True))
 
 import pytorch_lightning  # noqa: E402
 
@@ -321,15 +321,19 @@ def package_list_from_file(file):
     return mocked_packages
 
 
-MOCK_PACKAGES = package_list_from_file(os.path.join(PATH_ROOT, 'requirements-extra.txt'))
-if IS_READTHEDOCS_BUILD:
+MOCK_PACKAGES = []
+if SPHINX_MOCK_REQUIREMENTS:
     # mock also base packages when we are on RTD since we don't install them there
-    base_packages = package_list_from_file(os.path.join(PATH_ROOT, 'requirements.txt'))
-    MOCK_PACKAGES.extend(base_packages)
+    MOCK_PACKAGES += package_list_from_file(os.path.join(PATH_ROOT, 'requirements.txt'))
+    MOCK_PACKAGES += package_list_from_file(os.path.join(PATH_ROOT, 'requirements-extra.txt'))
 
 MOCK_MANUAL_PACKAGES = [
     'torchvision',
     'PIL',
+    # packages with different package name compare to import name
+    'yaml',
+    'comet_ml',
+    'neptune',
 ]
 autodoc_mock_imports = MOCK_PACKAGES + MOCK_MANUAL_PACKAGES