Does this suggestion already exist?

• This is a new feature!

Feature description

The current Sphinx-generated API reference is useful for learning basic usage patterns of the package.

However, there are many features of Feud, or ways to combine features that can be used in more complex usage patterns to achieve many different things in the generated CLI.

These detailed usage examples don't belong in the API reference, and should be contained in a separate user guide.

The user guide should also show integrations (which should work in theory), e.g. click-contrib and trogon.

Proposed stack

• mkdocs
  • mkdocs-material: Material design for mkdocs
  • koaning/mktestdocs: doctest but for mkdocs
  • jimporter/mike: multi-version mkdocs documentation
  • mkdocs-plugins/termynal: terminal window plugin for code blocks

Hosted at feud.wiki/guide or guide.feud.wiki.

Does this suggestion already exist?

• This is a new feature!

Feature description

Automatic documenation for Feud-generated commands would be useful for users.

It should be tested whether Sphinx can automatically pick up Click-decorated functions.

At the same time, it may be worth testing compatibility with https://github.com/click-contrib/sphinx-click.

Does this suggestion already exist?

• This is a new feature!

Feature description

Feud will currently break if from __future__ import annotations is used as the package relies on evaluated type hints.

Look into possible solutions to handle postponed type hint evaluation.

Does this suggestion already exist?

• This is a new feature!

Feature description

From the examples it seems like currently only numpy style docstrings are supported.

Is there any plan to support other docstring conventions. The 3 major ones in python are
Numpy
Google
rst

Does this suggestion already exist?

• This is a new feature!

Feature description

There is currently no easy way to check whether rich_click is installed and being used.

A simple way to do this is to change:

To:

#: Whether ``rich_click`` is installed or not.
is_rich: bool

try: 
    from rich_click import * 
    is_rich = True
except ImportError: 
    from click import * 
    is_rich = False

Then feud.click.is_rich can be used within the code base or by the user.

Existing parts of the code base relying on similar checks should be updated to re-use this variable.

Does this suggestion already exist?

• This is a new feature!

Feature description

Currently commands must be specified as members of a Group subclass when the subclass is defined, i.e.:

import feud

class CLI(feud.Group):
    def func():
        pass

In some cases, it may be useful to define the group first, then add the command later, e.g.:

import feud

def func1():
    pass

def func2():
    pass

class CLI(feud.Group):
    pass

CLI.add_commands(func1, func2)

Where func1/func2 may be a function, or a click.Command generated from @feud.command/@click.command/@click.group.

Proposed signature is:

import typing

class Group(...):
    def add_commands(
        cls: type[Group], 
        *args: click.Command | typing.Callable,
        **kwargs: click.Command | typing.Callable,
    ):
        ...

If called with keyword arguments, the key should be used as the name of the attribute added to the Group subclass.

The function should update __feud_commands__ on the subclass, and any other relevant attributes. It should probably check that there isn't already a class member with the same name.

If a function is provided, it should be wrapped with @feud.command(config=cls.__feud_config__).

Does this suggestion already exist?

• This is a new feature!

Feature description

As the code base is likely to grow, it's worth getting this in as soon as possible.

Does this suggestion already exist?

• This is a new feature!

Feature description

https://github.com/renovatebot/renovate can be used to automate dependency version upgrades.

Has this already been reported?

• This is a new bug!

Expected behaviour

All defined options are still shown with or without any *args.

def serve(port: int = 1, watch: bool = True, env: Literal["dev", "prod"] = "dev"):

python "main.py" --help
                                                                       
 Usage: main.py [OPTIONS]                                              
                                                                       
 Start a local HTTP server.                                            
                                                                       
╭─ Options ───────────────────────────────────────────────────────────╮
│ --port                INTEGER     Server port. [default: 1]         │
│ --watch/--no-watch                Watch source code for changes.    │
│                                   [default: watch]                  │
│ --env                 [dev|prod]  Environment mode. [default: dev]  │
│ --help                            Show this message and exit.       │
╰─────────────────────────────────────────────────────────────────────╯

Observed behaviour

Defined options are not shown if they are not preceded by *args

def serve(port: int = 1, watch: bool = True, env: Literal["dev", "prod"] = "dev"):

python "main.py" --help         
                                                                       
 Usage: main.py [OPTIONS] PORT WATCH {dev|prod}                        
                                                                       
 Start a local HTTP server.                                            
                                                                       
╭─ Options ───────────────────────────────────────────────────────────╮
│ --help      Show this message and exit.                             │
╰─────────────────────────────────────────────────────────────────────╯

If I add * or *args somewhere else except the last, then the rest of the commands after it is now shown

def serve(port: int = 1, watch: bool = True, *, env: Literal["dev", "prod"] = "dev"):

python "main.py" --help
                                                                       
 Usage: main.py [OPTIONS] PORT WATCH                                   
                                                                       
 Start a local HTTP server.                                            
                                                                       
╭─ Options ───────────────────────────────────────────────────────────╮
│ --env     [dev|prod]  Environment mode. [default: dev]              │
│ --help                Show this message and exit.                   │
╰─────────────────────────────────────────────────────────────────────╯

Code to reproduce

No response

Version details

Python: 3.12.1
Feud: 0.1.4
Operating system: Debian 12-bookworm