SP-1931 / added documentation for readthedocs

.gitignore

@@ -9,3 +9,4 @@ test
 *~
 *%
 doc
+docs/build

.readthedocs.yaml

@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: '3.12'
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements-docs.txt

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements-docs.txt

@@ -0,0 +1 @@
+furo

docs/source/conf.py

@@ -0,0 +1,28 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'SCANOSS Engine'
+copyright = '2024, Scan Open Source Solutions SL'
+author = 'Scan Open Source Solutions SL'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+html_logo = 'scanosslogo.jpg'
+html_static_path = ['_static']

docs/source/index.rst

@@ -0,0 +1,117 @@
+================================
+Documentation for SCANOSS Engine
+================================
+
+The SCANOSS Engine is an open, configurable OSS engine that was built specifically for developers, empowering them to confidently produce compliant code from the moment they begin writing, while delivering greater license and usage visibility for the broader DevOps team and supply chain partners.
+
+With its open architecture that is easy to integrate into existing processes and toolchains, SCANOSS transforms software bill of materials (SBOM) creation from 'write now, audit later' to an always-on analysis of live code.
+
+By freeing developers to focus on writing great, compliant code that they and their team can completely trust, applications are finished earlier, quality is consistently higher, and development costs are dramatically lower.
+
+Setup
+-----
+
+The Scanoss engine requires a Knowledge database installed for retrieving results. Scanoss use the SCANOSS LDB (Linked-list database) as a shared library. LDB Source code and installation guide can be found on https://github.com/scanoss/ldb
+
+The knowledge database is incrementally built using the SCANOSS mining tool (minr). It source code and installation guide can be found on https://github.com/scanoss/minr
+
+Prerequisites
+-------------
+
+* LDB shared library. Installation instructions: `LDB README <https://github.com/scanoss/ldb/blob/master/README.md>`_. Minimum version 4.1.0.
+* libgcrypt-dev
+
+Installation
+-------------
+
+The SCANOSS Engine is a command-line tool used for comparing a file or directory against the SCANOSS Knowledgebase. The source code can be downloaded and compiled as follows::
+
+    wget -O engine.zip https://github.com/scanoss/engine/archive/master.zip
+    unzip engine.zip
+    cd engine-master
+    make
+    sudo make install
+    cd ..
+    scanoss -v
+
+If you want to try scanoss without install it, execute this command in bash::
+
+    export LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH
+
+The last command should show the installed version of the SCANOSS Engine.
+
+Usage
+-----
+This program performs an OSS inventory for the given TARGET comparing against the ScanOSS LDB Knowledgebase. Results are printed in STDOUT in JSON format.
+You can create your own knowledgebase with the minr command, available at https://github.com/scanoss/minr
+
+**Syntax**: scanoss [parameters] [TARGET]
+
+Configuration:
+~~~~~~~~~~~~~~
+
+* ``-w`` Treats TARGET as a .wfp file regardless of the actual file extension
+* ``-s FILE`` Use assets specified in the provided JSON SBOM (CycloneDX/SPDX2.2 JSON format) as input to identification
+* ``-b FILE`` Ignore matches to assets specified in the provided JSON SBOM (CycloneDX/SPDX2.2 JSON format)
+
+Options:
+~~~~~~~~
+
+* ``-t`` Tests engine performance
+* ``-v`` Display version and exit
+* ``-h`` Display this help and exit
+* ``-d`` Enable debugging information
+
+File matching logic
+--------------------
+
+The scanning engine attempts to match files with the following criteria:
+
+Is the file matching an entire package?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(matching directly the archive downloaded from the URL)
+
+This produces an identification (id) of type "url"
+
+Is the file matching an entire known file?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This produces an identification (id) of type "file"
+
+Snippet comparison execution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Comparing snippet hashes produces an identification (id) of type "snippet"
+
+If none of the above
+~~~~~~~~~~~~~~~~~~~~
+
+This produces an identification (id) of type "none"
+
+File ranking algorithm
+----------------------
+
+Often, the SCANOSS engine finds files that are present in different components and versions, which triggers a series of functions to determine the best match. These functions are detailed below:
+
+Component hint retrieval
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The scanning client can optionally pass a component hint (context). The context is the name of the last component detected. This context will influence results and the scanning engine will favour the files belonging to a component matching the provided context.
+
+First component released
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If no hint is provided, the SCANOSS engine will look for the oldest component in the KB which matches the scanned file. In case of a tie between two components with the same release date, other available information will be used to select the best match.
+
+SBOM Ingestion
+~~~~~~~~~~~~~~
+
+The user can use the "-s" optional argument plus a sbom.json. The engine will prioritize the declared components during the analysis. If a file cannot be matched against any declared component, then the logic previously explained will be applied.
+
+License
+-------
+
+The Scanoss Open Source Engine is released under the GPL 2.0 license. Please check the LICENSE file for more information.
+
+Copyright (C) 2018-2020 SCANOSS.COM