Adds Travis-CI for sphinx-build and linkcheck

This adds test scripts to check build status of Spinx Documentation along with adding checks for broken links. Also fixes some broken links and updates doc_maintenance.rst Signed-off-by: Ayan Sinha Mahapatra <ayansmahapatra@gmail.com>
nexB · Jun 12, 2019 · 70cc71c · 70cc71c
1 parent d5b1de7
commit 70cc71c
Show file tree

Hide file tree

Showing 18 changed files with 47 additions and 17 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -0,0 +1,11 @@
+sudo: false
+language: python
+python:
+    - "3.6"
+install:
+    - pip install Sphinx sphinx_rtd_theme 
+before_install:
+  - chmod +x ./docs/scripts/sphinx_build_link_check.sh
+script:
+  - cd docs 
+  - ./scripts/sphinx_build_link_check.sh
diff --git a/docs/scripts/sphinx_build_link_check.sh b/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
diff --git a/docs/source/aboutcode-data/abcd.rst b/docs/source/aboutcode-data/abcd.rst
@@ -1,3 +1,5 @@
+.. _aboutcode_data:
+
 AboutCode Data : ABCD 
 =====================
 

diff --git a/docs/source/aboutcode-docs/contributor_project_ideas.rst b/docs/source/aboutcode-docs/contributor_project_ideas.rst
@@ -189,8 +189,7 @@ as a 2017 GSoC project) and rename it as the AboutCode server.
 The features of this updated server would be:
 
 
-- Store any ABC data including ScanCode scans See
-  https://github.com/nexB/aboutcode/tree/master/aboutcode-data)
+- Store any ABC data including ScanCode scans See :ref:`aboutcode_data`
 
 - Organize the data in projects (including possibly user-private projects)
 

diff --git a/docs/source/aboutcode-docs/gsoc_2017.rst b/docs/source/aboutcode-docs/gsoc_2017.rst
@@ -137,7 +137,7 @@ Use automated code translation (for JS) for the port.  Add license expression su
   * https://github.com/nexB/license-expression 
   * https://github.com/bastikr/boolean.py
   * https://github.com/nexB/aboutcode-manager
-  * https://github.com/jashkenas/coffeescript/wiki/list-of-languages-that-compile-to-js#python
+  * https://github.com/jashkenas/coffeescript/wiki/list-of-languages-that-compile-to-js
 
 - **Mentors**  : 
 

diff --git a/docs/source/aboutcode-toolkit/specification.rst b/docs/source/aboutcode-toolkit/specification.rst
@@ -46,7 +46,7 @@ The meaning of this ABOUT file is:
 - The home URL for this component is http://httpd.apache.org
 
 - The file "httpd-2.4.3.tar.gz" was originally downloaded from
-  http://archive.apache.org/dist/httpd/httpd-2.4.3.tar.gz
+  ``http://archive.apache.org/dist/httpd/httpd-2.4.3.tar.gz``
 
 - In the same directory, "apache-2.0.LICENSE" and "httpd.NOTICE" are files that
   contain respectively the license text and the notice text for this component.
@@ -209,7 +209,7 @@ Field referencing a URL
 
 The value of a field may reference URLs such as a homepage or a download. In
 this case the field name is suffixed with "_url" and the field value must be a
-valid absolute URL starting with ftp://, http:// or https://. URLs are
+valid absolute URL starting with ``ftp://``, ``http://`` or ``https://``. URLs are
 informational and the content they may reference is ignored. For example, a
 download URL is referenced this way::
 

diff --git a/docs/source/deltacode/json_to_csv.rst b/docs/source/deltacode/json_to_csv.rst
@@ -5,12 +5,12 @@ JSON to CSV Conversion
 
 The default output format for a DeltaCode codebase comparison is JSON.  If the ``-j`` or ``--json-file`` option is included in the ``deltacode`` command, the output will be written to a ``.json`` file at the user-designated location.  For example:
 
-.. code-block::
+::
 
    deltacode -n [path to the 'new' codebase] -o [path to the 'old' codebase] -j [path to the JSON output file]
 
 We have also created an easy-to-use script for users who want to convert their JSON output to CSV format.  Located at ``etc/scripts/json2csv.py``\ , the conversion can be run with this command template:
 
-.. code-block::
+::
 
     python etc/scripts/json2csv.py [path to the JSON input file] [path to the CSV output file]
diff --git a/docs/source/deltacode/release_process.rst b/docs/source/deltacode/release_process.rst
@@ -6,7 +6,7 @@ Steps to cut a new release:
 
 run bumpversion with major, minor or patch to bump the version in:
 
-.. code-block::
+::
 
    src/deltacode/__init__.py
    setup.py
@@ -15,14 +15,14 @@ run bumpversion with major, minor or patch to bump the version in:
 Update the CHANGELOG.rst
 commit changes and push changes to develop:
 
-.. code-block::
+::
 
    git commit -m "commit message"
    git push --set-upstream origin develop
 
 merge develop branch in master and tag the release.
 
-.. code-block::
+::
 
    git checkout master
    git merge develop

diff --git a/docs/source/doc_maintenance.rst b/docs/source/doc_maintenance.rst
@@ -71,6 +71,13 @@ Review your work::
     make html
     open build/html/index.html
 
+AboutCode uses Travis-CI to test build status and check links, so run this script at your local system before creating a Pull Request. 
+
+::
+
+    cd docs
+    ./scripts/sphinx_build_link_check.sh
+
 Share AboutCode Document Improvements
 -------------------------------------
 

diff --git a/docs/source/help.rst b/docs/source/help.rst
@@ -18,7 +18,7 @@ AboutCode Projects
 
 - `license-expression <https://github.com/nexB/license-expression/>`_: This is a library to parse, analyze, compare and normalize SPDX-like license expressions using a boolean logic expression engine. See https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60 to understand what a license expression is. See https://github.com/nexB/license-expression for the code. The underlying boolean engine is at https://github.com/bastikr/boolean.py . Both are co-maintained by @pombredanne
 
-- `ABCD aka AboutCode Data <https://github.com/nexB/aboutcode/blob/master/aboutcode-data/README.rst>`_: is a simple set of conventions to define data structures that all the AboutCode tools can understand and use to exchange data. The specification lives in this repository. .ABOUT files and ScanCode tooklit data are examples of this approach. Other projects such as https://libraries.io and `OSS Review Toolkit <https://github.com/heremaps/oss-review-toolkit>`_ also use these conventions.
+- `ABCD aka AboutCode Data <https://github.com/AyanSinhaMahapatra/aboutcode/blob/master/docs/source/aboutcode-data/abcd.rst>`_: is a simple set of conventions to define data structures that all the AboutCode tools can understand and use to exchange data. The specification lives in this repository. .ABOUT files and ScanCode tooklit data are examples of this approach. Other projects such as https://libraries.io and `OSS Review Toolkit <https://github.com/heremaps/oss-review-toolkit>`_ also use these conventions.
 
 - `DeltaCode <https://github.com/nexB/deltacode>`_ is a command line tool to compare scans and determine if and where there are material differences that affect licensing. The lead maintainer is @majurg
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -11,6 +11,7 @@ Guide
    scancode-workbench/index
    aboutcode-data/abcd
    aboutcode-docs/home
+   deltacode/index
    aboutcode-toolkit/index
    deltacode/index
    license

diff --git a/docs/source/scancode-toolkit/developement.rst b/docs/source/scancode-toolkit/developement.rst
@@ -24,6 +24,8 @@ We write tests, a lot of tests, thousands of tests. Several tests are data-drive
 
 When finding bugs or adding new features, we add tests. See existing test code for examples.
 
+.. _scancode_toolkit_developement_running_tests:
+
 Running tests
 -------------
 

diff --git a/docs/source/scancode-toolkit/documentation.rst b/docs/source/scancode-toolkit/documentation.rst
@@ -6,7 +6,7 @@ This page provides an index of current ScanCode user documentation.
 Download
 --------
 
-Download the latest release of ScanCode from our `release page <https://github.com/nexB/scancode-toolkit/releases.>`_ 
+Download the latest release of ScanCode from our `release page <https://github.com/nexB/scancode-toolkit/releases>`_ .
 
 Installation
 ------------

diff --git a/docs/source/scancode-toolkit/faq.rst b/docs/source/scancode-toolkit/faq.rst
@@ -110,6 +110,8 @@ More (advanced) rules options:
 
 	license_choice: yes
 
+.. _scancode_toolkit_faq_how_to_get_started_with_developement:
+
 How to get started with development?
 ------------------------------------
 
@@ -138,7 +140,7 @@ To run the tests faster on four processors in parallel run::
 
 	py.test -n 4
 
-See also https://github.com/nexB/scancode-toolkit/wiki/Development#running-tests for more details
+See also :ref:`scancode_toolkit_developement_running_tests` for more details
 
 More info:
 

diff --git a/docs/source/scancode-toolkit/how_to/how_to_run_a_scan.rst b/docs/source/scancode-toolkit/how_to/how_to_run_a_scan.rst
@@ -43,7 +43,7 @@ Static html output
 
 Scan the ``samples`` directory for licenses and copyrights and save the scan results to an HTML file.  When the scan is done, open ``samples.html`` in your web browser.
 
-.. code-block::
+::
 
    ./scancode --format html samples samples.html
 

diff --git a/docs/source/scancode-toolkit/ide_configaration.rst b/docs/source/scancode-toolkit/ide_configaration.rst
@@ -1,7 +1,7 @@
 IDE Configuration
 =================
 
-The instructions below assume that you followed the `steps to set up a development environment <https://github.com/nexB/scancode-toolkit/wiki/FAQ#how-to-get-started-with-development>`_ including a python virtualenv.
+The instructions below assume that you followed the :ref:`scancode_toolkit_faq_how_to_get_started_with_developement` including a python virtualenv.
 
 PyCharm
 -------

diff --git a/docs/source/scancode-toolkit/roadmap.rst b/docs/source/scancode-toolkit/roadmap.rst
@@ -64,7 +64,7 @@ Core features
 - |white_large_square| scan baselining, delta scan and failure conditions (such as license change, etc) (will be spawned as its own DeltaCode project)
 - |white_large_square| dedupe and similarities to avoid re-scanning. For now only identical files are scanned only once.
 - |white_large_square| Improved logging, tracing and error diagnostics
-- |clock1030| native support for ABC Data (See https://github.com/nexB/aboutcode/blob/master/aboutcode-data/README.rst )
+- |clock1030| native support for ABC Data (See :ref:`aboutcode_data` )
 
 Classification, summarization and deduction
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/docs/source/scancode-workbench/basics/platform_support.rst b/docs/source/scancode-workbench/basics/platform_support.rst
@@ -46,7 +46,8 @@ Our approach for platform support is to focus on one primary release for each of
 
 Electron Supported Platforms
 ----------------------------
-https://electron.atom.io/docs/tutorial/supported-platforms/
+
+https://electronjs.org/docs/tutorial/support#supported-platforms
 
 The following platforms are supported by Electron: