Skip to content

Commit 520c147

Browse files
tleonhardttleonhardt
committed
Improved the documentation for all cmd2 examples
1 parent dec3177 commit 520c147

File tree

5 files changed

+105
-13
lines changed

5 files changed

+105
-13
lines changed

‎docs/examples/examples.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# List of cmd2 examples
2+
3+
{%
4+
include-markdown "../../examples/README.md"
5+
%}

‎docs/examples/index.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
<!--intro-start-->
44

5-
- [First Application](first_app.md)
6-
- [Alternate Event Loops](alternate_event_loops.md)
5+
- [First Application](first_app.md)
6+
- [Alternate Event Loops](alternate_event_loops.md)
7+
- [List of cmd2 examples](examples.md)
78

89
<!--intro-end-->

‎examples/README.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# cmd2 Examples
2+
3+
The [examples](https://github.com/python-cmd2/cmd2/tree/master/examples) directory within the `cmd2` repository contains a number of simple self-contained examples which each demonstrate a few particular features of `cmd2`. None of them are representative of a full real-world complex `cmd2` application, if you are looking for that then see [Projects using cmd2](https://github.com/python-cmd2/cmd2?tab=readme-ov-file#projects-using-cmd2).
4+
5+
## List of cmd2 examples
6+
7+
Here is the list of examples in alphabetical order by filename along with a brief description of each:
8+
9+
- [alias_startup.py](https://github.com/python-cmd2/cmd2/blob/master/examples/alias_startup.py)
10+
- Demonstrates how to add custom command aliases and how to run an initialization script at startup
11+
- [arg_decorators.py](https://github.com/python-cmd2/cmd2/blob/master/examples/arg_decorators.py)
12+
- Demonstrates how to use the `cmd2.with_argparser` decorator to specify command arguments using [argparse](https://docs.python.org/3/library/argparse.html)
13+
- [arg_print.py](https://github.com/python-cmd2/cmd2/blob/master/examples/arg_print.py)
14+
- Demonstrates how arguments and options get parsed and passed to commands and shows how shortcust work
15+
- [argparse_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/argparse_completion.py)
16+
- Shows how to integrate tab-completion with argparse-based commands
17+
- [async_printing.py](https://github.com/python-cmd2/cmd2/blob/master/examples/async_printing.py)
18+
- Shows how to asynchronously print alerts, update the prompt in realtime, and change the window title
19+
- [basic.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic.py)
20+
- Shows how to add a command, add help for it, and create persistent command history for your application
21+
- [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py)
22+
- Show how to enable custom tab completion by assigning a completer function to `do_*` commands
23+
- [cmd2_as_argument.py](https://github.com/python-cmd2/cmd2/blob/master/examples/cmd_as_argument.py)
24+
- Demonstrates how to accept and parse command-line arguments when invoking a cmd2 application
25+
- [colors.py](https://github.com/python-cmd2/cmd2/blob/master/examples/colors.py)
26+
- Show various ways of using colorized output within a cmd2 application
27+
- [custom_parser.py](https://github.com/python-cmd2/cmd2/blob/master/examples/custom_parser.py)
28+
- Demonstrates how to create your own customer `Cmd2ArgumentParser`; used by the `override_parser.py` example
29+
- [decorator_example.py](https://github.com/python-cmd2/cmd2/blob/master/examples/decorator_example.py)
30+
- Shows how to use cmd2's various argparse decotrators to processes command-line arguments
31+
- [default_categories.py](https://github.com/python-cmd2/cmd2/blob/master/examples/default_categories.py)
32+
- Demonstrates usage of `@with_default_category` decorator to group and categorize commands and `CommandSet` use
33+
- [dynamic_commands.py](https://github.com/python-cmd2/cmd2/blob/master/examples/dynamic_commands.py)
34+
- Shows how `do_*` commands can be dynamically created programatically at runtime
35+
- [environment.py](https://github.com/python-cmd2/cmd2/blob/master/examples/environment.py)
36+
- Shows how to create custom `cmd2.Settable` parameters which serve as internal environment variables
37+
- [event_loops.py](https://github.com/python-cmd2/cmd2/blob/master/examples/event_loops.py)
38+
- Shows how to integrate a `cmd2` application with an external event loop which isn't managed by `cmd2`
39+
- [example.py](https://github.com/python-cmd2/cmd2/blob/master/examples/example.py)
40+
- This example is intended to demonstrate `cmd2's` build-in transcript testing capability
41+
- [exit_code.py](https://github.com/python-cmd2/cmd2/blob/master/examples/exit_code.py)
42+
- Show how to emit a non-zero exit code from your `cmd2` application when it exits
43+
- [first_app.py](https://github.com/python-cmd2/cmd2/blob/master/examples/first_app.py)
44+
- Short application that demonstrates 8 key features: Settings, Commands, Argument Parsing, Generating Output, Help, Shortcuts, Multiple Commands, and History
45+
- [hello_cmd2.py](https://github.com/python-cmd2/cmd2/blob/master/examples/hello_cmd2.py)
46+
- Completely bare-bones `cmd2` application suitable for rapid testing and debugging of `cmd2` itself
47+
- [help_categories.py](https://github.com/python-cmd2/cmd2/blob/master/examples/help_categories.py)
48+
- Demonstrates command categorization and its impact on the output of the built-in `help` command
49+
- [hooks.py](https://github.com/python-cmd2/cmd2/blob/master/examples/hooks.py)
50+
- Shows how to use various `cmd2` application lifecycle hooks
51+
- [initialization.py](https://github.com/python-cmd2/cmd2/blob/master/examples/initialization.py)
52+
- Shows how to colorize output, use multiline command, add persistent history, and more
53+
- [migrating.py](https://github.com/python-cmd2/cmd2/blob/master/examples/migrating.py)
54+
- A simple `cmd` application that you can migrate to `cmd2` by changing one line
55+
- [modular_commands_basic.py](https://github.com/python-cmd2/cmd2/blob/master/examples/modular_commands_basic.py)
56+
- Demonstrates based `CommandSet` usage
57+
- [modular_commands_dynamic.py](https://github.com/python-cmd2/cmd2/blob/master/examples/modular_commands_dynamic.py)
58+
- Demonstrates dynamic `CommandSet` loading and unloading
59+
- [modular_commands_main.py](https://github.com/python-cmd2/cmd2/blob/master/examples/modular_commands_main.py)
60+
- Complex example demonstrating a variety of methods to load `CommandSets` using a mix of command decorators
61+
- [modular_subcommands.py](https://github.com/python-cmd2/cmd2/blob/master/examples/modular_subcommands.py)
62+
- Shows how to use dynamically add and remove subcommands at runtime using `CommandSets`
63+
- [override-parser.py](https://github.com/python-cmd2/cmd2/blob/master/examples/override_parser.py)
64+
- Shows how to override cmd2's default `Cmd2ArgumentParser` with your own customer parser class
65+
- [paged_output.py](https://github.com/python-cmd2/cmd2/blob/master/examples/paged_output.py)
66+
- Shows how to use output pagination within `cmd2` apps via the `ppaged` method
67+
- [persistent_history.py](https://github.com/python-cmd2/cmd2/blob/master/examples/persistent_history.py)
68+
- Shows how to enable persistent history in your `cmd2` application
69+
- [pirate.py](https://github.com/python-cmd2/cmd2/blob/master/examples/pirate.py)
70+
- Demonstrates many features including colorized output, multiline commands, shorcuts, defaulting to shell, etc.
71+
- [python_scripting.py](https://github.com/python-cmd2/cmd2/blob/master/examples/python_scripting.py)
72+
- Shows how cmd2's built-in `run_pyscript` command and provide advanced Python scripting of cmd2 applications
73+
- [read_input.py](https://github.com/python-cmd2/cmd2/blob/master/examples/read_input.py)
74+
- Demonstrates the various ways to call `cmd2.Cmd.read_input()` for input history and tab completion
75+
- [remove_builtin_commands.py](https://github.com/python-cmd2/cmd2/blob/master/examples/remove_builtin_commands.py)
76+
- Shows how to remove any built-in cmd2 commands you do not want to be present in your cmd2 application
77+
- [remove_settable.py](https://github.com/python-cmd2/cmd2/blob/master/examples/remove_settable.py)
78+
- Shows how to remove any of the built-in cmd2 `Settables` you do not want in your cmd2 application
79+
- [subcommands.py](https://github.com/python-cmd2/cmd2/blob/master/examples/subcommands.py)
80+
- Shows how to use `argparse` to easily support sub-commands within your cmd2 commands
81+
- [table_creation.py](https://github.com/python-cmd2/cmd2/blob/master/examples/table_creation.py)
82+
- Contains various examples of using cmd2's table creation capabilities
83+
- [unicode_commands.py](https://github.com/python-cmd2/cmd2/blob/master/examples/unicode_commands.py)
84+
- Shows that cmd2 supports unicode everywhere, including within command names

‎examples/migrating.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
#!/usr/bin/env python
22
# coding=utf-8
33
"""
4-
A sample application for cmd which can be used to show how to migrate to cmd2.
4+
A sample cmd application that shows how to trivially migrate a cmd application to use cmd2.
55
"""
66

7-
import cmd
7+
# import cmd2 as cmd
8+
import cmd # Comment this line and uncomment the one above to migrate to cmd2
89
import random
910

1011

‎mkdocs.yml‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
site_name: cmd2
33
site_description: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python.
44
site_dir: build/html
5-
site_url: !ENV [READTHEDOCS_CANONICAL_URL, https://cmd2.readthedocs.io/]
5+
site_url: !ENV [READTHEDOCS_CANONICAL_URL, https://cmd2.readthedocs.io/]
66

77
# Repository
88
repo_name: cmd2
@@ -72,18 +72,18 @@ plugins:
7272
python:
7373
options:
7474
extensions:
75-
- griffe_typingdoc
75+
- griffe_typingdoc
7676
show_root_heading: true
7777
show_if_no_docstring: true
7878
preload_modules:
79-
- argparse
80-
- cmd
79+
- argparse
80+
- cmd
8181
inherited_members: true
8282
members_order: source
8383
separate_signature: true
8484
unwrap_annotated: true
8585
filters:
86-
- '!^_'
86+
- "!^_"
8787
merge_init_into_class: true
8888
docstring_section_style: spacy
8989
signature_crossrefs: true
@@ -122,9 +122,9 @@ markdown_extensions:
122122
- pymdownx.smartsymbols
123123
- pymdownx.superfences:
124124
custom_fences:
125-
- name: mermaid
126-
class: mermaid
127-
format: !!python/name:pymdownx.superfences.fence_code_format
125+
- name: mermaid
126+
class: mermaid
127+
format: !!python/name:pymdownx.superfences.fence_code_format
128128
- pymdownx.tabbed:
129129
alternate_style: true
130130

@@ -189,6 +189,7 @@ nav:
189189
- examples/index.md
190190
- examples/first_app.md
191191
- examples/alternate_event_loops.md
192+
- examples/examples.md
192193
- Plugins:
193194
- plugins/index.md
194195
- plugins/external_test.md
@@ -219,4 +220,4 @@ extra_css:
219220

220221
# Include extra JS to setup Read the Docs addons integrations
221222
extra_javascript:
222-
- javascripts/readthedocs.js
223+
- javascripts/readthedocs.js

0 commit comments

Comments
 (0)