Add default configuration file for all the rules

[mnojek]

To make it easier for the users to enable/disable selected rules and other CLI options, we can provide a default configuration file that will also contain all community rules (marked as disabled) and a comment next to each option explaining briefly what it does.

Something like this .pylintrc file here.

That way, people would not need to go through documentation of all the rules, they will just quickly skim through the configuration file, and they should at least has some basic understanding if they need it.

We can also add some robocop init command that will produce such file.

This task is part of the #809 issue.

[bhirsz]

1. Should comment in the configuration file be generated from the help docs? ie:

        optional.add_argument(
            "--language",
            "--lang",
            action=ParseDelimitedArgAction,
            default=self.language,
            help="Parse Robot Framework files using additional languages.",
        )

should produce:

# Parse Robot Framework files using additional languages
--language x

2. (bit of obvious, but still need to be asked) It should put default values? In above case, it should produce

--language en

For 2), it's not always easily possible to reuse default value - since default is sometimes already parsed value. We could add something like "default_config_value" or "raw_default" for such cases.

3. Should we support .robocop, pyproject.toml or both?

[bhirsz]

4. If there is config file in current directory already, it should not produce anything and print warning

[bhirsz]

5. In the top of the such file we should have some note like "Generated with Robocop x.y.z"
6. Some options should be commented and some not. For example:

--threshold I  # fine to include
# --ignore-default # it's better to not use this it by default

With such requirements I'm thinking it should be better to not overcomplicate things and do not create fully automatic solution but semi one. For example we can have class for producing the configuration files with some options manually added in the code and some options (like included rules) could be auto-generated.

As opposed, we could refactor our config class a bit to have something along:

Options = [
RobocopOption(name="", default..., argparse_config.., toml_config, ..)
]

And then use such list to create argparse and toml parsers, and use it for generating the default config.

[mnojek]

1. I would say – yes. It will be easier to maintain the short descriptions of the CLI options in one place. And if we see that the description is not very good, it will be a good moment to update them.

2. Yes, we should provide all enabled CLI options with default values, and all that are not used should be commented out. Regarding the parsed values – what do you mean here? Can you provide an example when we can't put the default value as is?

3. Good question. I think we definitely should have our own default config available for the users as a .robocop file, but having a possibility to also generate the TOML config is good, but such file can already exist in the user's project, so we need to think how to walkaround. We can either generate an additional TOML file so that the user can copy the content of it and put into an existing TOML file, or we can try to append Robocop configuration to an existing TOML file.

4. If there is a configuration file already, we should definitely not allow overwriting it by default.
   The more I think about it, I see a potential here that we can have a new command under robocop like robocop generate and then some CLI options to control it, e.g. -f to force overwriting, -o for pointing an output path or changing name of the config file, --format for selecting TOML or Robocop configuration file type, and so on... But this makes this feature a big addition to Robocop 😋
   For a simple solution, I would say we should not overwrite and display a warning.

5. Agreed.

6. This relates to 2) where I mentioned that some options should be commented out, and I agree that this complicates the generation a bit, because it would be hard to make it fully automatic (or we can do it by adding some flag to the options marking them as commented out or not).

[bhirsz]

2. In most cases, for example:

        optional.add_argument(
            "-rules",
            "--ext-rules",
            action=ParseDelimitedArgAction,
            default=self.ext_rules,
            help="List of paths with custom rules.",
        )

--ext-rules accepts string with comma delimited names. While self.ext_rulesis already parsed container (empty set). For such case I will display some example value, ie --ext-rules custom_rules.py

3. We can for now generate both .robocop and toml file. I will check if it will be easy to merge with existing pyproject.toml. It's preferable since it will work out of the box (if we create different file, like robocop.toml, it will not be recognized. Workaround would be to also detect such file together with pyproject.toml and .robocop.

4. In such case it would generate existing configuration to configuration file (be it default or with some overwritten values). Definitely possible but like you wrote - bit more complex. We can go with default configuration first and see how it'll be implemented (with the possibility of extending it later).

I will try to create some POC because it could clear out some problems if I will be able to achieve it easily.

[bhirsz]

I have managed to implement POC that reuses existing code for creating argument parser (by moving it to separate class). Thanks for adding few extra arguments like whether given option should be included in default config/commented out/default value overwritten I have produced:

# Generated with Robocop 3.2.1

# Run Robocop only with specified rules. You can define rule by its name or id.
# Glob patterns are supported.
# --include

# Ignore specified rules. You can define rule by its name or id.
# Glob patterns are supported.
# --exclude

# List of paths with custom rules.
# --ext-rules robocop_rules.py

# Use this flag to stop scanning directories recursively.
# --no-recursive

# Generate reports after scan.
# You can enable reports by listing them in comma-separated list:
# --reports rules_by_id,rules_by_error_type,scan_timer
# To enable all default reports use 'all':
# --reports all
# List available reports with --list-reports option.
--reports all

# Format of output message. You can use placeholders to change the way an issue is reported.
# Default: {source}:{line}:{col} [{severity}] {rule_id} {desc} ({name})
--format {source}:{line}:{col} [{severity}] {rule_id} {desc} ({name})

# Configure checker or report with parameter value. Usage:
# -c message_name_or_id:param_name:param_value
# Examples:
# -c line-too-long:line_length:150
# --configure 0101:severity:E
# --configure

# List all available rules. You can use optional PATTERN argument to match rule names (for example --list *doc*). PATTERN can be also ENABLED/DISABLED keyword to list only enabled/disabled rules.
# --list

# List all available rules with configurable parameters. You can use optional PATTERN argument to match rule names (for example --list *doc*). PATTERN can be also ENABLED/DISABLED keyword to list only enabled/disabled rules.
# --list-configurables

# List all available reports. Pass ENABLED or DISABLED as argument to list only enabled/disabled reports.
# --list-reports

# Path to output file.
# --output robocop_output.txt

# Comma-separated list of file extensions to be scanned by Robocop
--filetypes .robot,.tsv,.resource

# Disable rules below given threshold. Available message levels: I < W < E
--threshold I

# Path to file with arguments.
# --argumentfile robocop_config.txt

# Path to TOML configuration file.
# --config robocop_config.toml

# Ignore file(s) and path(s) provided. Glob patterns are supported.
# --ignore file_to_ignore.robot

# Parse Robot Framework files using additional languages.
# --language en

# Use this flag to save Robocop reports in cache directory for later comparison.
# --persistent

# Display extra information during execution.
--verbose

The next step would be extending include with commented rule names, ie:

# --include rule1
# --incldue rule2