Merge pull request #1 from nexB/master

Upsyncing

Author: TG1999

docs/source/conf.py

@@ -14,6 +14,14 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+# Adding Support for GIFs in Sphinx
+from sphinx.builders.html import StandaloneHTMLBuilder
+StandaloneHTMLBuilder.supported_image_types = [
+    'image/svg+xml',
+    'image/gif',
+    'image/png',
+    'image/jpeg'
+]
 
 # -- Project information -----------------------------------------------------
 

docs/source/doc_maintenance.rst

@@ -1,29 +1,56 @@
 Document Maintenance
 ====================
 
-Sphinx
-------
+Document Software Setup
+-----------------------
 
-Install Sphinx on your local machine.
-See http://www.sphinx-doc.org/en/master/usage/installation.html
+AboutCode documentation is built using Sphinx.
+See http://www.sphinx-doc.org/en/master/index.html
+
+AboutCode documentation is distributed using "Read the Docs".
+See https://readthedocs.org/
+
+Individual document files are in reStructuredText format.
+See http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+
+You create, build, and preview AboutCode documentation on your local machine.
+
+You commit your updates to the AboutCode repository on GitHub, which triggers an automatic rebuild of https://aboutcode.readthedocs.io/en/latest/index.html
 
 
 Clone AboutCode
 ---------------
 
-Create or identify a working directory on your local machine.
+To get started, create or identify a working directory on your local machine.
 
-Open that directory and execute the following commands in a terminal session::
+Open that directory and execute the following command in a terminal session::
 
     git clone https://github.com/nexB/aboutcode.git
-    git status
+
+That will create an /aboutcode directory in your working directory.
+Now you can install the dependencies in a virtualenv::
+
+    cd aboutcode
+    python3.6 -m venv .
+    source bin/activate
+
+Now you can install Sphinx and the format theme used by readthedocs::
+
+    pip install Sphinx sphinx_rtd_theme
+
+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 documentaiton .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
 
+In case this command did not work, for example on Ubuntu 18.04 you may get a message like “Couldn’t get a file descriptor referring to the console”, try: ::
+
+    see build/html/index.html
+
 You now have a local build of the AboutCode documents.
 
 Improve AboutCode Documents
@@ -50,8 +77,8 @@ Share AboutCode Document Improvements
 Follow standard git procedures to upload your new and modified files. The following commands are examples::
 
     git status
-    git add docs/source/index.rst
-    git add docs/source/how-to-scan.rst
+    git add source/index.rst
+    git add source/how-to-scan.rst
     git status
     git commit -m "New how-to document that explains how to scan"
     git status

docs/source/help.rst

@@ -6,21 +6,21 @@ AboutCode is a suite of open source projects.
 AboutCode Projects
 ******************
 
-- **[ScanCode Toolkit](https://github.com/nexB/scancode-toolkit)**: This is a set of code scanning tools to detect the origin and license of code and dependencies. ScanCode Toolkit uses a plug-in architecture to run a series of scan-related tools in one process flow. This is the most popular project and is used by hundreds of software teams. https://github.com/nexB/scancode-toolkit . The lead maintainer is @pombredanne
+- `ScanCode Toolkit <https://github.com/nexB/scancode-toolkit>`_: This is a set of code scanning tools to detect the origin and license of code and dependencies. ScanCode Toolkit uses a plug-in architecture to run a series of scan-related tools in one process flow. This is the most popular project and is used by hundreds of software teams. https://github.com/nexB/scancode-toolkit . The lead maintainer is @pombredanne
 
-- **[Scancode Workbench](https://github.com/nexB/scancode-workbench)** (formerly AboutCode Manager) This is a desktop application (based on Electron) to review the results of a scan and document your conclusions about the origin and license of software components and packages. https://github.com/nexB/aboutcode-manager . The lead maintainer is @majurg
+- `Scancode Workbench <https://github.com/nexB/scancode-workbench>`_ (formerly AboutCode Manager) This is a desktop application (based on Electron) to review the results of a scan and document your conclusions about the origin and license of software components and packages. https://github.com/nexB/aboutcode-manager . The lead maintainer is @majurg
 
-- **[AboutCode Toolkit](https://github.com/nexB/aboutcode-toolkit)**: This is a set of command line tools to document the provenance of your code and generate attribution notices.  AboutCode Toolkit uses small yaml files to document code provenance inside a codebase. https://github.com/nexB/aboutcode-toolkit . The lead maintainer is @chinyeungli
+- `AboutCode Toolkit <https://github.com/nexB/aboutcode-toolkit>`_: This is a set of command line tools to document the provenance of your code and generate attribution notices.  AboutCode Toolkit uses small yaml files to document code provenance inside a codebase. https://github.com/nexB/aboutcode-toolkit . The lead maintainer is @chinyeungli
 
-- **[TraceCode Toolkit](https://github.com/nexB/tracecode-toolkit)**: This is a set of tools to trace files from your deployment or distribution packages back to their origin in a development codebase or repository.  The primary tool uses strace https://github.com/strace/strace/ to trace system calls on Linux and construct a build graph from syscalls to show which files are used to build a binary. We are contributors to strace. Maintained by @pombredanne
+- `TraceCode Toolkit <https://github.com/nexB/tracecode-toolkit>`_: This is a set of tools to trace files from your deployment or distribution packages back to their origin in a development codebase or repository.  The primary tool uses strace https://github.com/strace/strace/ to trace system calls on Linux and construct a build graph from syscalls to show which files are used to build a binary. We are contributors to strace. Maintained by @pombredanne
 
-- **[Conan](https://github.com/nexB/conan)**: "conan" stands for "CONtainer ANalysis" and is a tool to analyze the structure and provenance of software components in Docker images using static analysis. https://github.com/nexB/conan Maintained by @pombredanne
+- `Conan <https://github.com/nexB/conan>`_: "conan" stands for "CONtainer ANalysis" and is a tool to analyze the structure and provenance of software components in Docker images using static analysis. https://github.com/nexB/conan Maintained by @pombredanne
 
-- **[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
+- `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** 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/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.
 
-- **[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
+- `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
 
-- **[VulnerableCode](https://github.com/nexB/vulnerablecode)**: an emerging server-side application to collect and track known package vulnerabilities.
+- `VulnerableCode <https://github.com/nexB/vulnerablecode>`_: an emerging server-side application to collect and track known package vulnerabilities.
 

docs/source/index.rst

@@ -5,8 +5,10 @@ Guide
 *****
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
+   scancode-toolkit/index
+   scancode-workbench/index
    license
    help
    doc_maintenance

docs/source/scancode-toolkit/clock.png

@@ -0,0 +1,107 @@
+Comprehensive Installation
+==========================
+
+ScanCode requires Python 2.7.x and is tested on Linux, Mac, and Windows. Make sure Python 2.7 is installed first.
+
+System Requirements
+-------------------
+
+- Hardware : ScanCode will run best with a modern X86 processor and at least 2GB of RAM and 250MB of disk.
+
+- Supported operating systems : ScanCode should run on these OSes:
+
+	#. Linux: on most recent 64-bit Linux distributions (32-bit distros are only partially supported),
+	#. Mac: on recent Mac OSX (10.6.8 and up),
+	#. Windows: on Windows 7 and up (32- or 64-bit) using a 32-bit Python.
+
+Prerequisites
+-------------
+ScanCode needs a Python 2.7 interpreter.
+
+- On Linux: Use your package manager to install python2.7. If Python 2.7 is not available from your package manager, you must compile it from sources. For instance, visit https://github.com/dejacode/about-code-tool/wiki/BuildingPython27OnCentos6 for instructions to compile Python from sources on Centos.
+
+- On Ubuntu 12.04, 14.04 and 16.04, you will need to install these packages first: ``python-dev bzip2 xz-utils zlib1g libxml2-dev libxslt1-dev``
+
+- On Debian and Debian-based distros you will need to install these packages first: ``python-dev libbz2-1.0 xz-utils zlib1g libxml2-dev libxslt1-dev``
+
+- On RPM-based distros, you will need to install these packages first: ``python-devel zlib bzip2-libs xz-libs libxml2-devel libxslt-devel``
+
+- **On Windows**:
+
+	Use the Python 2.7 32-bit (e.g. the Windows x86 MSI installer) for X86 regardless of whether you run Windows on 32-bit or 64-bit. DO NOT USE Python X86_64 installer even if you run 64 bit Windows. Download Python from this url: https://www.python.org/ftp/python/2.7.13/python-2.7.13.msi
+
+	Install Python on the c: drive and use all default installer options(scancode will try to find python just in c:\python27\python.exe). See the Windows installation section for more installation details.
+
+- On Mac: Download and install Python from this url: https://www.python.org/ftp/python/2.7.13/python-2.7.13-macosx10.6.pkg
+
+Do not use Unicode, non-ASCII in your installation Path
+-------------------------------------------------------
+There is a bug in underlying libraries that prevent this.
+
+Installation on Linux and Mac
+-----------------------------
+
+Download and extract the latest ScanCode release from:
+https://github.com/nexB/scancode-toolkit/releases/latest
+
+Open a terminal in the extracted directory and run::
+
+	./scancode --help       
+
+This will configure ScanCode and display the command line help.
+
+Installation on Windows
+-----------------------
+
+- Download the latest ScanCode release zip file from https://github.com/nexB/scancode-toolkit/releases/latest
+
+- In Windows Explorer (called File Explorer on Windows 10), select the downloaded ScanCode zip and right-click.
+
+- In the pop-up menu select 'Extract All...'
+
+- In the pop-up window 'Extract zip folders' ('Extract Compressed (Zipped) Folders' on Windows 10) use the default options to extract.
+
+- Once the extraction is complete, a new Windows Explorer/File Explorer window will pop up.
+
+- In this Explorer window, select the new folder that was created and right-click.
+
+	* On Windows 10, double-click the new folder, select one of the files inside the folder (e.g., 'setup.py'), and right-click.
+- In the pop-up menu select 'Properties'.
+
+- In the pop-up window 'Properties', select the Location value. Copy this to the clipboard and close the 'Properties' window.
+
+- Press the start menu button. (On Windows 10, click the search box or search icon in the taskbar.)
+
+- In the search box type::
+
+	cmd
+
+- Select 'cmd.exe' listed in the search results. (On Windows 10, you may see 'Command Prompt' instead -- select that.)
+
+- A new 'cmd.exe' window ('Command Prompt' on Windows 10) pops up.
+
+- In this window (aka a 'command prompt'), type the following (i.e., 'cd' followed by a space)::
+
+	cd
+
+- Right-click in this window and select Paste. This will paste the path where you extracted ScanCode.
+
+- Press Enter.
+
+- This will change the current location of your command prompt to the root directory where scancode is installed.
+
+- Then type::
+
+	scancode -h                                                                       
+
+- Press enter. This will configure your ScanCode installation.
+
+- Several messages are displayed followed by the scancode command help.
+
+- The installation is complete.
+
+Un-installation
+---------------
+
+- Delete the directory in which you extracted ScanCode.
+- Delete any temporary files created in your system temp directory under a scancode directory.