===================
Project changes
---------------
- Cloup license changed from MIT to 3-clause BSD, the one used by Click.
- Added a donation button.
New features and enhancements
-----------------------------
- Cloup now uses its own ``HelpFormatter``:
* it supports alignment of multiple definition lists, so Cloup doesn't have to
rely on a hack (padding) to align option groups and alike
* it adds theming of the help page, i.e. styling of several elements of the
help page
* it has an additional way to format definition lists (implemented with the
method ``write_linear_dl``) that kicks in when the available width for the
standard 2-column format is not enough (precisely, when the width available
for the 2nd column is below ``formatter.col2_min_width``)
* it adds several attributes to fine-tune and customize the generated help:
``col1_max_width``, ``col_spacing`` and ``row_sep``
* it fixes a couple of Click minor bugs and decides the column width of
definition lists in a slightly smarter way that makes a better use of the
available space.
- Added a custom ``Context`` that:
* uses ``cloup.HelpFormatter`` as formatter class by default
* adds a ``formatter_settings`` attributes that allows to set the default
formatter keyword arguments (the same argument can be given to a command to
override these defaults). You can use the static method
``HelpFormatter.settings`` to create such a dictionary
* allows to set the default value for the following ``Command``/``Group`` args:
* ``align_option_groups``,
* ``align_sections``
* ``show_constraints``
* has a ``Context.setting`` static method that facilitates the creation of a
``context_settings`` dictionary (you get the help of your IDE).
- Added a base class ``BaseCommand`` for ``Command`` and ``Group`` that:
- extends ``click.Command``
- back-ports Click 8.0 class attribute ``context_class`` and set it to ``cloup.Context``
- adds the ``formatter_settings`` argument
- Hidden option groups. An option group is hidden either if you pass
``hidden=True`` when you define it or if all its contained options are hidden.
If you set ``hidden=True``, all contained options will have their ``hidden``
attribute set to ``True`` automatically.
- Adds the conditions ``AllSet`` and ``AnySet``.
* The ``and`` of two or more ``IsSet`` conditions returns an ``AllSet`` condition.
* The ``or`` of two or more ``IsSet`` conditions returns an ``AnySet`` condition.
- Changed the error messages of ``all_or_none`` and ``accept_none``.
- The following Click decorators are now exported by Cloup: ``argument``,
``confirmation_option``, ``help_option``, ``pass_context``, ``pass_obj``,
``password_option`` and ``version_option``.
Breaking changes
----------------
These incompatible changes don't affect the most "external" API used by most
clients of this library.
- Formatting methods of ``OptionGroupMixin`` and ``SectionMixin`` now expects
the ``formatter`` to be a ``cloup.HelpFormatter``.
If you used a custom ``click.HelpFormatter``, you'll need to change your code
if you want to use this release. If you used ``click-help-colors``, keep in
mind that the new formatter has built-in styling capabilities so you don't
need ``click-help-colors`` anymore.
- ``OptionGroupMixin.format_option_group`` was removed.
- ``SectionMixin.format_section`` was removed.
- The class ``MultiCommand`` was removed, being useless.
- The ``OptionGroupMixin`` attribute ``align_option_groups`` is now ``None`` by default.
Functionally, nothing changes: option groups are aligned by default.
- The ``SectionMixin`` attribute ``align_sections`` is now ``None`` by default.
Functionally, nothing changes: subcommand sections are aligned by default.
- The ``ConstraintMixin`` attribute ``show_constraints`` is now ``None`` by default.
Functionally, nothing changes: constraints are **not** shown by default.
Docs
----
- Switch theme to ``furo``.
- Added section "Help formatting and theming".
- Improved all sections.
--------------------------------------------------------------------------------