Lint and cleanup documentation

pombredanne · pombredanne · commit f4c10ed380da · 2021-08-02T09:37:53.000+02:00
Signed-off-by: Philippe Ombredanne &lt;pombredanne@nexb.com&gt;
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -18,8 +18,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'ScanCode-Toolkit'
-copyright = '2019 ScanCode-Toolkit.org'
-author = 'ScanCode-Toolkit.org'
+copyright = 'nexB Inc. and others.'
+author = 'AboutCode.org authors and contributors'
 
 
 # -- General configuration ---------------------------------------------------
diff --git a/docs/source/contribute/contrib_dev.rst b/docs/source/contribute/contrib_dev.rst
@@ -9,7 +9,7 @@ TL;DR:
 - Source code and runtime data are in the /src/ directory.
 - Test code and test data are in the /tests/ directory.
 - Datasets (inluding licenses) and test data are in /data/ sub-directories.
-- We use DCO signoff in commit messages, like Linux does. 
+- We use DCO signoff in commit messages, like Linux does.
 - Porting ScanCode to other OS (FreeBSD is supported, etc.) is possible. Enter an issue for help.
 
 See `CONTRIBUTING.rst <https://github.com/nexB/scancode-toolkit/blob/master/CONTRIBUTING.rst>`_
@@ -45,21 +45,19 @@ new features, we add tests. See existing test code for examples which form also
 a good specification for the supported features.
 
 The tests should pass on Linux 64 bits, Windows 64 bits and on
-macOS 10.14 and up. We maintain multiple CI loops with Azure (all OSes) 
+macOS 10.14 and up. We maintain multiple CI loops with Azure (all OSes)
 at https://dev.azure.com/nexB/scancode-toolkit/_build and Appveyor (Windows) at
 https://ci.appveyor.com/project/nexB/scancode-toolkit .
 
 
 Several tests are data-driven and use data files as test input and sometimes
 data files as test expectation (in this case using either JSON or YAML files);
 a large number of copyright, license and package manifest parsing tests are such
-data-driven tests. 
-
+data-driven tests.
 
 
 .. _scancode_toolkit_development_running_tests:
 
-
 Running tests
 -------------
 
@@ -120,7 +118,7 @@ Thirdparty libraries and dependencies management
 
 ScanCode uses the ``configure`` and ``configure.bat`` scripts to install a
 `virtualenv <https://virtualenv.pypa.io/en/stable/>`_ , install required
-packaged dependencies using  `setuptools <https://github.com/pypa/setuptools>`_ 
+packaged dependencies using  `setuptools <https://github.com/pypa/setuptools>`_
 and such that ScanCode can be installed in a repeatable and consistent manner on
 all OSes and Python versions.
 
@@ -141,16 +139,16 @@ store it in the Git repo in the ``etc/thirdparty`` directory.
 We bundle pre-built bundled native binaries as plugins which are installed as
 wheels. These binaries are organized by OS and architecture; they ensure that
 ScanCode works out of the box either using a checkout or a download, without
-needing a compiler and toolchain to be installed. 
+needing a compiler and toolchain to be installed.
 
 The corresponding source code and build scripts for all for the
-pre-built binaries are stored in a separate repository at 
+pre-built binaries are stored in a separate repository at
 https://github.com/nexB/scancode-plugins
 
 ScanCode app archives should not require network access for installation or
-configuration of its third-party libraries and dependencies. To enable this, 
+configuration of its third-party libraries and dependencies. To enable this,
 we store bundled thirdparty components and  libraries in the ``thirdparty``
-directory of released app archives; this is done at build time. 
+directory of released app archives; this is done at build time.
 These dependencies are stored as pre-built wheels. These wheels are sometimes
 built by us when there is no wheel available upstream on PyPI. We store all
 these prebuilt wheels with corresponding .ABOUT and .LICENSE files in
@@ -159,7 +157,7 @@ for download at  https://thirdparty.aboutcode.org/pypi/
 
 Because this is used by the configure script, all the thirdparty dependencies
 used in ScanCode MUST be available there first. Therefore adding a new
-dependency means requesting a merge/PR in 
+dependency means requesting a merge/PR in
 https://github.com/nexB/thirdparty-packages/ first that contains all the
 recursive dependencies.
 
diff --git a/docs/source/getting-started/home.rst b/docs/source/getting-started/home.rst
@@ -19,14 +19,19 @@ is often much harder to accomplish than it should be because:
 ScanCode tries to address these issues by offering:
 
 - A simple command line approach that runs on Windows, Linux, and macOS
-- A comprehensive code scanner that can detect origin and license information in codebase files, including binaries
-- A comprehensive set of package manifests and lockfile parsers to report direct and pinned dependencies
-- Your choice of JSON or other output formats (YAML, SPDX, HTML, CSV) for integration with other tools
+- A comprehensive code scanner that can detect origin and license information in
+  codebase files, including binaries
+- A comprehensive set of package manifests and lockfile parsers to report direct
+  and pinned dependencies
+- Your choice of JSON or other output formats (YAML, SPDX, HTML, CSV) for
+  integration with other tools
 - Well-tested, easy to hack, and well-documented code
 - A plugin system for easily adding new Functionality to Scans.
 - Extensive documentation and support.
-- We release of the code and reference data under permissive licenses (Apache 2.0 and CC-BY-4.0)
-- ScanCode.io to assemble scripted and specialied code analysis pipelines with a web-based analysis server
+- We release of the code and reference data under permissive licenses (Apache
+  2.0 and CC-BY-4.0)
+- ScanCode.io to assemble scripted and specialied code analysis pipelines with
+  a web-based analysis server
 - ScanCode workbench for desktop-based scans visualization
 
 ScanCode is recognized as the industry leading engine for license and copyright
@@ -43,7 +48,7 @@ ScanCode detects and normalizes origin, dependencies, licensing and other
 related information in your code:
 
 - by parsing package manifests and dependencies lock files to a normalized
-  metadata model and assigning each an identifying `Package URL 
+  metadata model and assigning each an identifying `Package URL
   <https://github.com/package-url/purl-spec>`_,
 
 - by detecting license tags, notices and texts in text and binaries using the
diff --git a/docs/source/getting-started/install.rst b/docs/source/getting-started/install.rst
@@ -1,7 +1,8 @@
 Comprehensive Installation
 ==========================
 
-There are 4 main ways you can install ScanCode.
+
+There are four main ways to install ScanCode.
 
 - :ref:`app_install`
 
@@ -63,17 +64,22 @@ ScanCode needs a Python 3.6+ interpreter; We support all Python versions from
 
     For Ubuntu, it is ``sudo apt install python3-dev``
 
-    - On Ubuntu 14, 16, 18 and 20 run:
-      ``sudo apt install python-dev bzip2 xz-utils zlib1g libxml2-dev libxslt1-dev libpopt0``
+    - On Ubuntu 14, 16, 18 and 20 run::
+
+          sudo apt install python-dev bzip2 xz-utils zlib1g libxml2-dev libxslt1-dev libpopt0
+
+    - On Debian and Debian-based distros run::
+
+          sudo apt-get install python3-dev libbz2-1.0 xz-utils zlib1g libxml2-dev libxslt1-devlibpopt0
+
+    - On RPM-based distros run::
+
+          sudo yum install python3.6-devel zlib bzip2-libs xz-libs libxml2-devel libxslt-devellibpopt0
 
-    - On Debian and Debian-based distros run:
-      ``sudo apt-get install python3-dev libbz2-1.0 xz-utils zlib1g libxml2-dev libxslt1-devlibpopt0``
+    - On Fedora 22 and later run::
 
-    - On RPM-based distros run:
-      ``sudo yum install python3.6-devel zlib bzip2-libs xz-libs libxml2-devel libxslt-devellibpopt0``
+          sudo dnf install python3.6-devel xz-libs zlib libxml2-devel libxslt-devel bzip2-libs libpopt0
 
-    - On Fedora 22 and later run:
-      ``sudo dnf install python3.6-devel xz-libs zlib libxml2-devel libxslt-devel bzip2-libs libpopt0``
 
     If these packages are not available from your package manager, you must
     compile them  from sources.
@@ -280,7 +286,7 @@ using the following command::
 
     git checkout develop
 
-Here, ``develop`` branch has the latest release of Scancode-Toolkit. 
+Here, ``develop`` branch has the latest release of Scancode-Toolkit.
 You can also check out to any of the following:
 
 - Branches (Locally created or already present) [Example - ``develop``]
@@ -332,7 +338,7 @@ The steps are:
 
     /usr/bin/python3 -m venv .
 
-For more information on Python virtualenv, visit this 
+For more information on Python virtualenv, visit this
 `page <https://docs.python-guide.org/dev/virtualenvs/#lower-level-virtualenv>`_.
 
 #. Activate the virtual environment you just created::
diff --git a/docs/source/getting-started/newcomer.rst b/docs/source/getting-started/newcomer.rst
@@ -154,8 +154,7 @@ ScanCode Versions
 ^^^^^^^^^^^^^^^^^
 
 #. You can see all Scancode Toolkit versions on the `GitHub release page <https://github.com/nexB/scancode-toolkit/releases>`_.
-#. Refer :ref:`whats_new_this_release` to know more about the latest release.
-#. You can also refer the `CHANGELOG <https://github.com/nexB/scancode-toolkit/blob/develop/CHANGELOG.rst>`_ for more information on specific releases.
+#. Read the `CHANGELOG <https://github.com/nexB/scancode-toolkit/blob/develop/CHANGELOG.rst>`_ for more information on specific releases.
 #. If you want to use/test a specific version of Scancode Toolkit, you can follow the instructions
    in :ref:`source_code_install` docs.
 
@@ -239,12 +238,7 @@ To determine where to contribute, you can refer:
 #. ScanCode Toolkit tracks issues via the `GitHub Issue tracker <https://github.com/nexB/scancode-toolkit/issues>`_
 #. Broad `milestones <https://github.com/nexB/scancode-toolkit/milestones>`_ for upcoming versions are also maintained.
 
-And documentation related to contributing code can be referred at :ref:`contrib_code_dev`. The main
-sections are:
-
-#. :ref:`contrib_code_conven`
-#. :ref:`scancode_toolkit_developement_running_tests`
-#. :ref:`contrib_dev_pip_and_configure`
+And documentation related to contributing code can be referred at :ref:`contrib_code_dev`.
 
 .. _newcomer_good_first_issue:
 
@@ -332,9 +326,6 @@ Then:
 
      - :ref:`GSoC2019`
      - :ref:`GSoD2019`
-     - :ref:`GSoC2020`
-     - :ref:`GSoC2021`
-     - :ref:`GSoD2021`
 
 #. Remain active in Gitter and talk with the organization mentors well ahead of the deadlines.
 #. Select projects according to your skills and finalize project proposals.
diff --git a/docs/source/how-to-guides/add_new_license_detection_rule.rst b/docs/source/how-to-guides/add_new_license_detection_rule.rst
@@ -59,6 +59,6 @@ More (advanced) rules options:
 - if no license should be detected for your .RULE text, do not add a license expression,
   just add a ``notes`` field.
 
-- Each rules needs have one flag such as is_license_notice. See the 
+- Each rules needs have one flag such as is_license_notice. See the
   ``src/licensedcode/models.py`` directory for a list of all possible values and
   other options.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -94,7 +94,6 @@ Miscellaneous Documents
    :maxdepth: 2
 
    misc/index
-   license
 
 
 Discussion Documents
diff --git a/docs/source/license.rst b/docs/source/license.rst
diff --git a/docs/source/misc/faq.rst b/docs/source/misc/faq.rst
@@ -68,7 +68,7 @@ Can I install ScanCode in a Unicode path?
 -----------------------------------------
 
 Yes but but it is best to void this for now. See
-https://github.com/nexB/scancode- toolkit/issues/867 
+https://github.com/nexB/scancode- toolkit/issues/867
 
 There is a bug in virtualenv https://github.com/pypa/virtualenv/issues/457 that
 is now fixed but has not been extensively tested for ScanCode.
diff --git a/docs/source/tutorials/how_to_run_a_scan.rst b/docs/source/tutorials/how_to_run_a_scan.rst
@@ -8,7 +8,7 @@ by default with Scancode.
 Prerequisites
 -------------
 
-Refer to the :ref:`install` installation guide.
+Refer to the :ref:'install' installation guide.
 
 
 Looking into Files
