Skip to content

Commit

Permalink
docs: restyle README.md and related projects (#117)
Browse files Browse the repository at this point in the history
  • Loading branch information
eonu authored Dec 26, 2023
1 parent c9c8edd commit fcc9744
Show file tree
Hide file tree
Showing 2 changed files with 74 additions and 34 deletions.
102 changes: 73 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,19 +44,12 @@
</sup>
</p>

---

## About

> [!WARNING]
> _Writing command-line interfaces can get messy!_
It is not uncommon for CLIs to consist of many commands,
subcommands, arguments, options and aliases, on
top of dealing with other aspects such as documentation and input types when
it comes to argument parsing.

Designing such an interface can quickly spiral into chaos without the help of
Designing a _good_ CLI can quickly spiral into chaos without the help of
an intuitive CLI builder.

**Feud builds on [Click](https://click.palletsprojects.com/en/8.1.x/) for
Expand Down Expand Up @@ -657,6 +650,10 @@ $ python generate.py "dog barking" "cat meowing" --output audio.txt
</tr>
</table>

_By relying on Pydantic to handle the hard work of validation, we can contain all
of the required CLI constraints in a simple function signature, leaving you to focus
on the important part – implementing your commands._

### Highly configurable and extensible

> [!IMPORTANT]
Expand Down Expand Up @@ -857,72 +854,119 @@ Feud either relies heavily on, or was inspired by the following
packages. It would be greatly appreciated if you also supported the below
maintainers and the work they have done that Feud has built upon.
### [Click](https://github.com/pallets/click)
<table>
<tr>
<th>Project</th>
<th>Description</th>
</tr>
<tr>
<td>
##### [Click](https://github.com/pallets/click)
<sup>
by [@pallets](https://github.com/pallets)
by&nbsp;[@pallets](https://github.com/pallets)
</sup>
> _Click is a Python package for creating beautiful command line interfaces in a composable way with as little code as necessary._
</td>
<td>
Feud is essentially a wrapper around Click that takes classes and functions
with type hints and intelligently 'compiles' them into a ready-to-use Click
generated CLI.
### [Rich Click](https://github.com/ewels/rich-click)
</td>
</tr>
<tr>
<td>
##### [Rich Click](https://github.com/ewels/rich-click)
<sup>
by [@ewels](https://github.com/ewels)
by&nbsp;[@ewels](https://github.com/ewels)
</sup>
> _Richly rendered command line interfaces in click._
</td>
<td>
A shim around Click that renders help output nicely using
[Rich](https://github.com/Textualize/rich).
### [Pydantic](https://github.com/pydantic/pydantic)
</td>
</tr>
<tr>
<td>
##### [Pydantic](https://github.com/pydantic/pydantic)
<sup>
by [@samuelcolvin](https://github.com/samuelcolvin)
by&nbsp;[@samuelcolvin](https://github.com/samuelcolvin)
</sup>
> _Data validation using Python type hints._
</td>
<td>
Pydantic is a validation package that makes it easy to declaratively validate
input data based on type hints.
The package offers support for common standard library types (e.g. `int`,
`float`, `str`, `date`/`datetime`), plus more complex types which can also be
used as type hints in Feud commands for input validation.
The package offers support for common standard library types, plus more complex
types which can also be used as type hints in Feud commands for input validation.
### [Typer](https://github.com/tiangolo/typer)
</td>
</tr>
<tr>
<td>
##### [Typer](https://github.com/tiangolo/typer)
<sup>
by [@tiangolo](https://github.com/tiangolo)
by&nbsp;[@tiangolo](https://github.com/tiangolo)
</sup>
> _Typer is a library for building CLI applications that users will love using and developers will love creating._
</td>
<td>
Typer shares a similar ideology to Feud, in that building CLIs should be
simple and not require learning new functions or constantly referring to
library documentation. Typer is also based on Click.
One source of motivation for creating Feud is that at the time of creation,
Pydantic was not yet supported as a type system for Typer. It is worth
noting that Pydantic as an optional dependency is on Typer's [tentative roadmap](https://github.com/tiangolo/typer/issues/678),
so it will be interesting to see how the implementation compares to Feud!
Typer is a more complete library for building CLIs overall, but currently
lacks support for more complex types such as those offered by Pydantic.
</td>
</tr>
<tr>
<td>
##### [Thor](https://github.com/rails/thor)
<sup>
by&nbsp;[@rails](https://github.com/rails)
</sup>
</td>
<td>
Though not a Python package, the highly object-oriented design of Thor (a CLI
building package in Ruby) – in particular the use of classes to define command
groups – greatly influenced the implementation of the `feud.Group` class.
</td>
</tr>
</table>
## Contributing
All contributions to this repository are greatly appreciated. Contribution guidelines can be found [here](/CONTRIBUTING.md).
Expand Down
6 changes: 1 addition & 5 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -40,11 +40,7 @@ Feud

----

It is not uncommon for CLIs to consist of many commands, subcommands,
arguments, options and aliases, on top of dealing with other aspects such as
documentation and input types when it comes to argument parsing.

Designing such interfaces can spiral into chaos without the help of
Designing a *good* CLI can spiral into chaos without the help of
an intuitive CLI builder.

**Feud builds on** `Click <https://click.palletsprojects.com/en/8.1.x/>`__ **for
Expand Down

0 comments on commit fcc9744

Please sign in to comment.