Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Add Getting Started chapter (migrate from README) #773

Merged
merged 1 commit into from Jan 30, 2022
Merged

[docs] Add Getting Started chapter (migrate from README) #773

merged 1 commit into from Jan 30, 2022

Conversation

bittner
Copy link
Contributor

@bittner bittner commented Jan 16, 2022

Bandit's documentation has a strong focus on explaining Bandit development topics. Bandit users are puzzled, because the documentation gives absolutely no hints about how to install, use and configure (the use of) Bandit. Luckily, the project README does that in detail.

Other F/LOSS projects prove that it's a good idea to keep the README short and crisp, and move (user-focused) instructions to the documentation. – This is exactly what this PR does. The README prominently links to the documentation, so all is good.

Resolves: #603

Refactoring Details

  1. (Installation ... VC Integration) goes to "Getting Started" chapter.
  2. (Configuration) is omitted as it replicates content in the "Configuration" chapter.
  3. (Per Project CLA ... Exclusions) is added as section "Bandit Settings" to the "Configuration" chapter; the existing content gets "Scanning Behavior" as a section title.
  4. (Vulnerability Tests ... Extending Bandit) is omitted: These sections are already included in the CONTRIBUTING document; the "Writing Tests" section is also part of the "Bandit Test Plugins" chapter.
  5. (Under Which Version): This questions goes into a new chapter "FAQs".

I tried to change as little as possible of the original formatting (to keep the history of the content transition clean). I may update some of the formatting after this PR has been merged, or as additional commits here, if preferred.

@bittner
Copy link
Contributor Author

bittner commented Jan 28, 2022

I rebased the PR and resolved the conflict with the README. This could be merged now.

@bittner
Copy link
Contributor Author

bittner commented Jan 30, 2022

Can someone please approve the GHA workflow to be started and afterwards approve the changes, so that the PR could be merged?

Copy link
Member

@ericwb ericwb left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. The README is more concise now. I do think it could use some further work. The readme is mentioned how to contribute twice, yet no indication on how to install. References are typically at the end of a doc. I also think a gif demoing Bandit in action would be nice. Future PRs can address these things.

@ericwb ericwb merged commit 6c94c85 into PyCQA:master Jan 30, 2022
@bittner bittner deleted the docs/add-getting-started-from-readme branch January 30, 2022 17:48
@bittner
Copy link
Contributor Author

bittner commented Jan 30, 2022

Thanks for merging! 👍

@bittner
Copy link
Contributor Author

bittner commented Jan 30, 2022

Building the docs fails because they're still built with Python 2.7 and there is a version conflict. This should be easy to fix by having the docs built by Python 3.

@bittner
Copy link
Contributor Author

bittner commented Jan 30, 2022

Looks like the Python version is to be set in the RTD project settings.

@lukehinds Can you set the "Python Interpreter" option to "CPython 3.x" and retrigger the build, please?

@ericwb
Copy link
Member

ericwb commented Jan 30, 2022

@lukehinds also can you please add all the maintainers as admin to read-the-docs. Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Document how to use Bandit
2 participants