Fix -- separator handling and document aliases

[bw2]

Summary

This PR addresses two open issues by fixing the -- separator handling bug and documenting all available aliases.

Changes

1. Fix -- separator handling (Issue #298)

Problem: When using config files or environment variables with the -- separator, config/env args were incorrectly mixed with positional arguments that should come after --.

Example of the bug:

# With config file containing: list = [1, 2, 3]
./script.py -c config.toml -- foo bar

# Before fix (WRONG):
# positional_arg = ['foo', 'bar', '--list=3']  # Config arg leaked into positional!

# After fix (CORRECT):
# positional_arg = ['foo', 'bar']
# list = ['1', '2', '3']

Solution:

• Modified parse_known_args() in configargparse.py (lines 971-982 and 1067-1078)
• Config file and env var args are now inserted before the first optional argument (starting with -)
• This preserves the -- separator position and prevents args from being mixed
• Added comprehensive test case testDoubleDashSeparator() to verify the fix

Technical details:
The original code used the nargs flag to decide whether to append or prepend args. When action="append" was used, this caused config args to be appended to the end, placing them after --. The new implementation always inserts before the first optional arg, correctly handling the -- separator in all cases.

2. Document all available aliases (Issue #297)

Problem: ConfigArgParse provides many convenient aliases (like p.add(), p.parse(), ArgParser, etc.) that were used in examples but not properly documented.

Solution:

• Enhanced the "Aliases" section in README.rst
• Organized all aliases into clear categories:
  • Class Aliases: ArgParser, Parser
  • Method Aliases: p.add(), p.add_arg(), p.parse(), p.parse_known()
  • Function Aliases: get_parser(), get_arg_parser(), etc.
  • HelpFormatter Aliases: RawFormatter, DefaultsFormatter, etc.
• Each alias now clearly shows what it maps to

Testing

• Added new test case testDoubleDashSeparator() that tests:
  • Config file with -- separator
  • Config file without -- separator
  • Environment variables with -- separator
• All existing tests pass (64 tests, only expected TOML failures due to missing optional dependency)

Closes

• Closes ConfigArgParse is not handling the -- seperator for positional arguments correctly #298
• Closes Aliases used in example code are not documented #297

🤖 Generated with Claude Code