fix #1686: implement separate help menu and add documentation links.

[AdityaPatadiya]

This PR has done several changes that is given in issue#1686.

• split the existing help menu to short and full length help menu.
• adding documentation pages links of github.

Checklist

• No CHANGELOG update needed

• No new tests needed

• No documentation update needed

[gemini-code-assist]

Hello @AdityaPatadiya, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

Summary of Changes

This pull request addresses issue #1686 by implementing a separate help menu with short and full length options, and adding links to the documentation pages on GitHub. The changes involve modifying the argparse configuration to support the new help menu options and adding a function to handle the display of the help menus with relevant documentation links and examples.

Highlights

• Help Menu Separation: The existing help menu is split into short and full length versions, accessible via -h and --help respectively.
• Documentation Links: Links to the capa documentation pages on GitHub are added to the help menu.
• Argparse Configuration: The argparse configuration is modified to support the new help menu options, including disabling the default help flag and adding custom help actions.

Changelog

• capa/features/freeze/init.py
  • Modified the argparse.ArgumentParser constructor to disable the default help flag by setting add_help=False.
• capa/main.py
  • Added -h and --help arguments using parser.add_argument to trigger the short and full help menus, respectively.
  • Implemented the handle_help_from_cli function to generate and display the appropriate help menu based on the provided arguments. This function includes links to the online documentation.
  • Modified the main function to call handle_help_from_cli when -h or --help are provided as arguments, printing the help message and exiting the program.
• rules
  • Updated the subproject commit hash for the rules repository.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

---

Did you know?

The term 'RTFM' (Read The Fine Manual) is a common, often sarcastic, response to a question that is easily answered by consulting the documentation. This PR aims to make the 'manual' more accessible.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

Please add bug fixes, new features, breaking changes and anything else you think is worthwhile mentioning to the master (unreleased) section of CHANGELOG.md. If no CHANGELOG update is needed add the following to the PR description: [x] No CHANGELOG update needed

[gemini-code-assist]

Code Review

This pull request introduces a separate help menu and adds documentation links to the capa tool. The changes aim to improve the user experience by providing more accessible and detailed information about the tool's usage and features. The implementation appears well-structured, with clear separation of concerns. However, there are a few areas that could benefit from further refinement.

Summary of Findings

• Inconsistent Help Menu Behavior: The -h and --help flags are implemented using action="store_true" in argparse, but the help message is only displayed when these flags are explicitly checked in main() and handle_help_from_cli(). This deviates from the standard argparse behavior, where the help message is automatically displayed when these flags are present. This inconsistency might confuse users familiar with argparse.
• Duplication of Documentation Links: The documentation links are duplicated in the handle_help_from_cli() function. This redundancy increases the maintenance burden and the risk of inconsistencies. Consider defining these links as constants or variables to promote code reuse and maintainability.
• Missing fh_wanted Argument in Short Help Menu: The short help menu in handle_help_from_cli() does not pass the fh_wanted argument to install_common_args(). This discrepancy might lead to inconsistencies between the short and full help menus, potentially confusing users.

Merge Readiness

The pull request introduces valuable improvements to the capa tool's help menu and documentation accessibility. However, the identified inconsistencies and potential maintenance issues should be addressed before merging. I am unable to approve this pull request, and recommend that another reviewer approves this code before merging. Addressing the comments below will improve the code quality and user experience.

[gemini-code-assist]

The -h and --help arguments are defined here, but their behavior is overridden in the main() function. Consider using argparse's built-in help functionality to ensure consistent behavior and avoid potential conflicts.

Suggested change

	parser.add_argument("-h", action="store_true", help="display help menu and exit.")
	parser.add_argument("--help", action="store_true", help="display full length help menu and exit.")
	# parser.add_argument("-h", action="store_true", help="display help menu and exit.")
	# parser.add_argument("--help", action="store_true", help="display full length help menu and exit.")

[gemini-code-assist]

The short help menu does not pass the fh_wanted argument to install_common_args(). This might lead to inconsistencies between the short and full help menus. Consider passing fh_wanted to ensure both menus have the same set of arguments.

        parser = argparse.ArgumentParser(
            description=desc, epilog=short_epilog, formatter_class=argparse.RawDescriptionHelpFormatter, add_help=False
        )
        install_common_args(parser, fh_wanted) # pass fh_wanted to ensure consistency
        return parser.format_help()

[gemini-code-assist]

The -h and --help flags are checked here to display the help menu. However, argparse already provides built-in help functionality. Consider removing this check and relying on argparse to handle the help menu display. This will ensure consistent behavior and avoid potential conflicts.

    # if "-h" in argv or "--help" in argv:
    #     print(handle_help_from_cli(argv, wanted))
    #     sys.exit(0)

CHANGELOG updated or no update needed, thanks! 😄