Skip to content

Commit 2918688

Browse files
author
Jiahao Ren
committed
docs: add glossary of terms to general reference
Add a glossary defining key terms (Option, flag, command line application, command line utility, terminal, etc.) as they are used throughout the Click documentation. Uses MyST cross-references to link terms to their detailed documentation pages. Fixes #3077
1 parent 831c8f0 commit 2918688

2 files changed

Lines changed: 62 additions & 0 deletions

File tree

docs/glossary.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Glossary
2+
3+
```{currentmodule} click
4+
```
5+
6+
This glossary defines key terms as they are used throughout the Click
7+
documentation. Having a shared vocabulary helps keep the docs internally
8+
consistent and reduces ambiguity for new users.
9+
10+
## Terms
11+
12+
**Application**
13+
: A complete command line program built with Click. May consist of a
14+
single command or a tree of commands and groups. Used interchangeably
15+
with "command line application" in this documentation.
16+
17+
**Argument**
18+
: A positional parameter passed to a command. Arguments are
19+
required by default and are identified by their position on the
20+
command line, not by name. See {doc}`arguments`.
21+
22+
**Command**
23+
: A single callable unit in a Click application. Created with
24+
{func}`~click.command`. A command can accept
25+
{class}`~click.Option` and {class}`~click.Argument` parameters.
26+
See {doc}`commands`.
27+
28+
**Command line application**
29+
: A program that is operated by typing text commands into a terminal.
30+
In Click, this is any program built using the Click framework.
31+
Used interchangeably with "application".
32+
33+
**Command line utility**
34+
: A command line application designed for a specific task, often
35+
without a persistent interactive session. Examples include ``ls``,
36+
``grep``, and ``curl``. In Click documentation, "application" is
37+
preferred for clarity.
38+
39+
**Flag**
40+
: An option that takes no value, acting as a boolean switch. Created
41+
by passing `is_flag=True` to {func}`~click.option`. Example:
42+
``--verbose``. See {ref}`is-flag`.
43+
44+
**Group**
45+
: A command that contains subcommands. Created with
46+
{func}`~click.group`. Groups enable nested CLI structures where
47+
the first argument selects a subcommand. See {doc}`commands-and-groups`.
48+
49+
**Option**
50+
: A named parameter passed to a command using ``--name value`` or
51+
``--name=value`` syntax. Options are optional by default. See
52+
{doc}`options`.
53+
54+
**Parameter**
55+
: A generic term covering both {term}`options <Option>` and
56+
{term}`arguments <Argument>`. See {doc}`parameters`.
57+
58+
**Terminal**
59+
: The text-based interface where a command line application is
60+
executed. Also called a "console", "shell", or "command prompt".
61+
Click uses "terminal" throughout its documentation.

docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,7 @@ General Reference
118118
command-line-reference
119119
unicode-support
120120
wincmd
121+
glossary
121122

122123
API Reference
123124
-------------------

0 commit comments

Comments
 (0)