Merge pull request #1784 from AyanSinhaMahapatra/develop

Add Travis-CI tests for docs

Author: steven-esser

.travis.yml

@@ -90,6 +90,9 @@ addons:
         - pyenv
     update: true
 
+before_install:
+  - chmod +x ./docs/scripts/sphinx_build_link_check.sh
+  - chmod +x ./docs/scripts/doc8_style_check.sh
 
 install:
   - ./configure
@@ -99,6 +102,11 @@ script:
   # - ./bin/py.test -n 2 -vvs --cov=src tests/scancode
   # - echo $TEST_SUITE
   - $TEST_SUITE
+  # Documentation Test Scripts
+  - source bin/activate
+  - cd docs
+  - "./scripts/sphinx_build_link_check.sh"
+  - "./scripts/doc8_style_check.sh"
 
 # Pay attention to both calls below. They will succeed even if there
 # is no coverage information or connection to reporting website fails.

docs/requirements.txt

@@ -0,0 +1,29 @@
+alabaster==0.7.12
+Babel==2.7.0
+certifi==2019.9.11
+chardet==3.0.4
+doc8==0.8.0
+docutils==0.15.2
+idna==2.8
+imagesize==1.1.0
+Jinja2==2.10.3
+MarkupSafe==1.1.1
+packaging==19.2
+pbr==5.4.3
+Pygments==2.4.2
+pyparsing==2.4.2
+pytz==2019.3
+requests==2.22.0
+restructuredtext-lint==1.3.0
+six==1.12.0
+snowballstemmer==2.0.0
+Sphinx==2.2.0
+sphinx-rtd-theme==0.4.3
+sphinxcontrib-applehelp==1.0.1
+sphinxcontrib-devhelp==1.0.1
+sphinxcontrib-htmlhelp==1.0.2
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.2
+sphinxcontrib-serializinghtml==1.1.3
+stevedore==1.31.0
+urllib3==1.25.6

docs/scripts/doc8_style_check.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+# halt script on error
+set -e
+# Check for Style Code Violations
+doc8 --max-line-length 100 source --ignore D000 --quiet

docs/scripts/sphinx_build_link_check.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+# halt script on error
+set -e
+# Build locally, and then check links
+sphinx-build -E -W -b linkcheck source build

docs/source/conf.py

@@ -49,6 +49,6 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 master_doc = 'index'

docs/source/doc_maintenance.rst

@@ -44,7 +44,8 @@ Now you can build the HTML documents locally::
     cd docs
     make html
 
-Assuming that your Sphinx installation was successful, Sphinx should build a local instance of the documentation .html files::
+Assuming that your Sphinx installation was successful, Sphinx should build a local instance of the
+documentation .html files::
 
     open build/html/index.html
 
@@ -60,7 +61,8 @@ Ensure that you have the latest ScanCode Toolkit files::
     git pull
     git status
 
-Use your favorite text editor to create and modify .rst files to make your documentation improvements.
+Use your favorite text editor to create and modify .rst files to make your documentation
+improvements.
 
 Review your work::
 
@@ -71,7 +73,8 @@ Review your work::
 Share ScanCode Toolkit Document Improvements
 --------------------------------------------
 
-Follow standard git procedures to upload your new and modified files. The following commands are examples::
+Follow standard git procedures to upload your new and modified files. The following commands are
+examples::
 
     git status
     git add source/index.rst
@@ -82,4 +85,5 @@ Follow standard git procedures to upload your new and modified files. The follow
     git push
     git status
 
-The ScanCode Toolkit webhook with ReadTheDocs should rebuild the documentation. You can review your results online.
+The ScanCode Toolkit webhook with ReadTheDocs should rebuild the documentation. You can review your
+results online.

docs/source/index.rst

@@ -33,7 +33,8 @@ Reference documents describe application concepts in depth.
 Discussion Documents
 ====================
 
-Discussion documents provide insights into integration of the application into your own software development life cycle.
+Discussion documents provide insights into integration of the application into your own software
+development life cycle.
 
 
 Indices and Tables

setup.py

@@ -221,6 +221,12 @@ def read(*names, **kwargs):
         'spdx_tools >= 0.6.0',
         'unicodecsv',
 
+        # ScanCode Docs
+        'Sphinx <  2.0; python_version == "2.7"',
+        'Sphinx >= 2.0; python_version > "3"',
+        'sphinx_rtd_theme >= 0.4.3',
+        'doc8 >= 0.8.0',
+
         # ScanCode caching and locking
         'yg.lockfile >= 2.3, < 3.0.0',
             # used by yg.lockfile

thirdparty/Babel-2.7.0-py2.py3-none-any.whl

@@ -0,0 +1,17 @@
+about_resource: Babel-2.7.0-py2.py3-none-any.whl
+name: Babel
+version: 2.7.0
+checksum_md5: b96fe47047fd07bc5797779d903d4fe2
+checksum_sha1: 6145459f9d7a875b10695874588044157cff58be
+package_url: pkg:pypi/[email protected]
+download_url: https://files.pythonhosted.org/packages/2c/60/f2af68eb046c5de5b1fe6dd4743bf42c074f7141fe7b2737d3061533b093/Babel-2.7.0-py2.py3-none-any.whl
+notice_url: https://github.com/babel/babel/blob/master/LICENSE
+homepage_url: http://babel.pocoo.org/en/latest/
+owner_url: https://github.com/babel
+owner:  Armin Ronacher
+contact: [email protected]
+license_expression: bsd-new
+licenses:
+-   key: bsd-new
+    name: BSD-3-Clause
+copyright: Copyright (c) 2014-present Sebastian McKenzie and other contributors