Page MenuHomeSoftware Heritage

Improve cli documentation
ClosedPublic

Authored by tenma on Oct 2 2020, 3:04 PM.

Details

Summary

The docstring was moved out of scanner docstring spot to work around a bug in our current Python version. See https://bugs.python.org/issue28739

Related to D4089

Diff Detail

Repository
rDTSCN Code scanner
Branch
cli-doc
Lint
No Linters Available
Unit
No Unit Test Coverage
Build Status
Buildable 15891
Build 24462: Phabricator diff pipeline on jenkinsJenkins console · Jenkins
Build 24461: arc lint + arc unit

Event Timeline

Build has FAILED

Patch application report for D4130 (id=14558)

Rebasing onto ad23ee03c0...

Current branch diff-target is up to date.
Changes applied before test
commit 7d7846954e35a969bba2d85f234d272e1fdabfaf
Author: tenma <tenma+swh@mailbox.org>
Date:   Tue Sep 29 19:47:54 2020 +0200

    Improve cli documentation
    
    The docstring was moved out of scanner docstring spot to work around a
    bug in our current Python version. See https://bugs.python.org/issue28739

Link to build: https://jenkins.softwareheritage.org/job/DTSCN/job/tests-on-diff/55/
See console output for more information: https://jenkins.softwareheritage.org/job/DTSCN/job/tests-on-diff/55/console

zack added inline comments.
swh/scanner/cli.py
65

I guess you wanted this line to be CONFIG_FILE_HELP, and I don't get why CONFIG_FILE_HELP is referencing itself. Am I missing something magic or are these typos?

swh/scanner/cli.py
65

In fact, because of https://bugs.python.org/issue28739 and also because it is quite long text, I moved config details to the scanner help. It gives it more space and make it actually readable. Click does not let use format the text, it even removes single line breaks...
The config help was extracted to a constant to be pluggable where we need it.
Test it and see if

swh/scanner/cli.py
65

(sorry, last comment not complete)
Test it and see if you like it.
Also pay attention: there is 2 constants: CONFIG_FILE_HELP and SCANNER_HELP that references CONFIG_FILE_HELP.

Build has FAILED

Patch application report for D4130 (id=14575)

Rebasing onto ad23ee03c0...

Current branch diff-target is up to date.
Changes applied before test
commit dbe5bf7f7f0d1a499713a0f655f16e17238149e6
Author: tenma <tenma+swh@mailbox.org>
Date:   Tue Sep 29 19:47:54 2020 +0200

    Improve cli documentation
    
    The docstring was moved out of scanner docstring spot to work around a
    bug in our current Python version. See https://bugs.python.org/issue28739

Link to build: https://jenkins.softwareheritage.org/job/DTSCN/job/tests-on-diff/59/
See console output for more information: https://jenkins.softwareheritage.org/job/DTSCN/job/tests-on-diff/59/console

Fixed the cherry-picked commit

Build is green

Patch application report for D4130 (id=14577)

Rebasing onto ad23ee03c0...

Current branch diff-target is up to date.
Changes applied before test
commit 74b02366e97d4c85b5a9551a30f8339da1f95924
Author: tenma <tenma+swh@mailbox.org>
Date:   Tue Sep 29 19:47:54 2020 +0200

    Improve cli documentation
    
    The docstring was moved out of scanner docstring spot to work around a
    bug in our current Python version. See https://bugs.python.org/issue28739

See https://jenkins.softwareheritage.org/job/DTSCN/job/tests-on-diff/60/ for more details.

tested and confirmed—yes, I like it! thanks

This revision is now accepted and ready to land.Oct 2 2020, 10:37 PM

Finally found how to keep (paragraph) formatting with Click: "\n\n\b\n"

Build is green

Patch application report for D4130 (id=14610)

Rebasing onto ad23ee03c0...

Current branch diff-target is up to date.
Changes applied before test
commit 5c723326f97721df3c84c700c0ddafb53c7ad733
Author: tenma <tenma+swh@mailbox.org>
Date:   Tue Sep 29 19:47:54 2020 +0200

    Improve cli documentation
    
    The docstring was moved out of scanner docstring spot to work around a
    bug in our current Python version. See https://bugs.python.org/issue28739
    Its formatting was also improved.

See https://jenkins.softwareheritage.org/job/DTSCN/job/tests-on-diff/62/ for more details.

Build is green

Patch application report for D4130 (id=14618)

Rebasing onto 15875836f0...

Current branch diff-target is up to date.
Changes applied before test
commit ccf123a4cefd231263be90d31ca089734232ee18
Author: tenma <tenma+swh@mailbox.org>
Date:   Tue Sep 29 19:47:54 2020 +0200

    Improve cli documentation
    
    The docstring was moved out of scanner docstring spot to work around a
    bug in our current Python version. See https://bugs.python.org/issue28739
    Its formatting was also improved.

See https://jenkins.softwareheritage.org/job/DTSCN/job/tests-on-diff/63/ for more details.

This revision was automatically updated to reflect the committed changes.