diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 00000000..cc6af169 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/scripts/sphinx_build_link_check.sh b/docs/scripts/sphinx_build_link_check.sh new file mode 100755 index 00000000..c5426863 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/source/aboutcode-data/abcd.rst b/docs/source/aboutcode-data/abcd.rst index 49c239d6..8d45de47 100644 --- 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 index 976827c1..c4d26d72 100644 --- 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 index e9c424e8..772cfba0 100644 --- 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 index bfe418cb..df4ead8f 100644 --- 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 index 6a91efa7..158148d6 100644 --- 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 index 6fad7495..cc796129 100644 --- 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 index 4773f915..45ae4911 100644 --- 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 index 1ceaaf98..64b90185 100644 --- a/docs/source/help.rst +++ b/docs/source/help.rst @@ -18,7 +18,7 @@ AboutCode Projects - `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 `_: 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 `_ also use these conventions. +- `ABCD aka AboutCode Data `_: 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 `_ also use these conventions. - `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 index 5ce4aed8..5cba0957 100644 --- 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 index c43545e0..4eee83c8 100644 --- 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 index b3504331..2e5c83b1 100644 --- 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 `_ +Download the latest release of ScanCode from our `release page `_ . Installation ------------ diff --git a/docs/source/scancode-toolkit/faq.rst b/docs/source/scancode-toolkit/faq.rst index 8ee13f0b..12dd031f 100644 --- 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 index 6c46870a..13f0f34f 100644 --- 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 index ec8c4c4e..77f5ab7a 100644 --- 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 `_ 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 index dec7b9a5..1974709c 100644 --- 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 index 5a197962..25edddab 100644 --- 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: