Update documentation for v32

[AyanSinhaMahapatra]

Fixes #3277
Fixes #3278
Fixes #3298

Tasks

• Reviewed contribution guidelines
• PR is descriptively titled 📑 and links the original issue above 🔗
• Tests pass -- look for a green checkbox ✔️ a few minutes after opening your PR
  Run tests locally to check for errors.
• Commits are in uniquely-named feature branch and has no merge conflicts 📁

[AyanSinhaMahapatra]

Btw, doc builds for this branch are enabled and can be viewed here: https://scancode-toolkit.readthedocs.io/en/doc-update-licenses/

[johnmhoran]

docs/source/cli-reference/basic-options.rst

Lines 89-90: "If we run license detection (with --license-text) on the above text"

Perhaps put "--license-text" inside backticks? In my view of the RTD page, that flag is displayed with a single hyphen/dash, "-license-text", even though when copied and pasted from the RTD page to, e.g., Notepad+ I see a double-dash.

Line 124: change "occurances" to "occurrences"

Lines 669-670: In the code we have these 2 URLs, which look like markup inside this .rst file:

    [`WTFPL`](http://www.wtfpl.net/txt/copying/) and
    [`MIT`](https://opensource.org/licenses/MIT).

and in the RTD they show up like this (no idea how this will be displayed in my comment):

        [`WTFPL`](http://www.wtfpl.net/txt/copying/) and
        [`MIT`](https://opensource.org/licenses/MIT).

Maybe we want this instead?

        `WTFPL <http://www.wtfpl.net/txt/copying/>`_ and
        `MIT <https://opensource.org/licenses/MIT>`_.

Line 673: In "we have to following license detection result" replace "to" with "the"

Lines 748-752: In this passage:

    Here from the ``"detection_log": ["unknown-intro-followed-by-match"]`` added diagnostics
    information we get to know that there was a unknown intro license match, followed by
    proper detections, so we concluded the unknown intro to be a introduction to the
    following license and hence concluded the license from the license matches after the
    unknown detection.

consider

• replacing "get to know" with "learn"
• replacing "a unknown" with "an unknown"
• replacing "so we concluded" with "so we conclude"
• replacing "a introduction" with "an introduction"
• replacing "and hence concluded" with "and hence conclude"

[AyanSinhaMahapatra]

WTFPL

This is just an example file where this was markdown, we did not want a link here. So this is ok.
All other comments addressed.

[johnmhoran]

docs/source/cli-reference/scan-options-post.rst

Line 32: Change 'Their' to 'their' in Then, the following directories are marked as "Source", i.e. Their "is_source" attribute is set

Line 33: Change to "True", as they contain source code majorly. to to "True", as they contain mostly source code.

Line 56: In scancode-toolkit as top level packages, dependenices and licenses change dependenices to dependencies

Line 57: Change now provide a improved consolidated data. to now provide improved consolidated data.

Line 206: such as the ScanCode LicenseDB -- is that the current name of the DB?

Line 252: What does this mean?

It whole JSON file is structured as follows, when it has "license_clarity_score"::

Does this capture the intent?

When the "license_clarity_score" is included, the entire JSON file is structured as follows::

Line 349: change seperately to separately

Line 479: change comparision to comparison

Line 600: change dependenices to dependencies

[AyanSinhaMahapatra]

such as the ScanCode LicenseDB -- is that the current name of the DB?

Yes! See https://github.com/nexB/scancode-licensedb#scancode-licensedb and https://scancode-licensedb.aboutcode.org/

Addressed all comments otherwise.

[johnmhoran]

docs/source/contribute/contrib_doc.rst

Lines 319-323: Each of these 3 links takes me to a 404 page:

It's possible to generate docs automatically from data by using a combination of:

• shell scripts: example <https://github.com/nexB/scancode-toolkit/blob/develop/docs/scripts/regen_package_docs.sh>_
• python scripts: example <https://github.com/nexB/scancode-toolkit/blob/develop/src/packagedcode/regen_package_docs.py>_
• jinja templates: example <https://github.com/nexB/scancode-toolkit/blob/develop/src/packagedcode/templates/available_package_parsers.rst>_

[AyanSinhaMahapatra]

Yup, these would be working when we merge this PR :P As they are in this PR actually.

[johnmhoran]

docs/source/how-to-guides/add_new_license.rst

Line 9: In To add new license insert a before new.

Line 15: In numbers from 0 to 9,and add a space after the comma.

Line 18: In less than 50 characters change less to fewer.

Line 20: In "We also have to add a spdx_license_key" change a to an.

Line 24: In I.e. the filename change I.e. to For example,.

Line 30: Change characters, copyrights to characters (e.g., copyrights).

Line 33: In the data attributes for the license in YAML format as YAML frontmatter., what does as YAML frontmatter mean?

Line 46: Change but nice to have always to but always nice to have.

Line 54: Change which are very similar to that are very similar.

Line 55: Change make sure we match correctly these licenses to make sure we match these licenses correctly.

Line 79: Change developement to development.

Line 80: Change to make sure we reindex the licenses and this validates the new licenses. to to make sure we reindex the licenses (and this also validates the new licenses).

[AyanSinhaMahapatra]

See https://github.com/eyeseast/python-frontmatter, also added this link here. It's a way of adding metadata to plain text files. We recently added this to half the number of files under data/licenses/

Comments addressed, thanks!

[johnmhoran]

docs/source/how-to-guides/add_new_license_detection_rule.rst

Line 32: Change this name, for example to this name; for example,.

Line 35: In Save your rule text in this file, if there are specific words, change , to ;.

Line 64: Change Each rules needs have one flag to describe the type of license rule, the options are: to Each rule needs to have one flag to describe the type of license rule. The options are:`

Line 86: Change to make sure we reindex the rules and this validates the new licenses. to to make sure we reindex the rules (and this also validates the new licenses).

[AyanSinhaMahapatra]

Not adding the last parenthesis, as it's not a side effect, that is the reason why we run the reindexing.

Addressed other comments, thanks!

[johnmhoran]

docs/source/reference/available_package_parsers.rst

Line 8: Scancode supports -- let's try to be consistent with our product naming -- at least change this to ScanCode, although it's actually ScanCode Toolkit, isn't it?

[AyanSinhaMahapatra]

Chnaged to ScanCode. It's both scancode.io and scancode-toolkit, as scancode.io also uses toolkit and this is also what is supported there.

[johnmhoran]

docs/source/rst_snippets/note_snippets/post_license_policy.rst

Lines 6-9: The full passage:

We do not have
licenses as an required option because this plugin would be
upgraded to also include the license policy attribute for
packages too.

• Change an required option to a required option.
• I don't understand what we are trying to say with this portion of the passage:

because this plugin would be
upgraded to also include the license policy attribute for
packages too.

[AyanSinhaMahapatra]

We could have made the --license option a required option to run --license-policy, but that's not the case because in the future, this would also include packages.

[johnmhoran]

@AyanSinhaMahapatra I've completed my review of the 59 files.

[AyanSinhaMahapatra]

@johnmhoran thanks a lot for the feedback and comments, they were really helpful in making the documentation better, more correct and consistent. Have addressed all comments and kept some answers unresolved above for you to see.