Skip to content

Commit 84c5a46

Browse files
dbieberdbieber
committed
- Rename doc to docs in preparation for adding mkdocs support.
- Adds additional public documentation to Python Fire. Copybara generated commit for Python Fire. PiperOrigin-RevId: 162004265 Change-Id: I356c966d74d2270cc59abaff7238913339d17609 Reviewed-on: https://team-review.git.corp.google.com/82464 Reviewed-by: David Bieber <[email protected]>
1 parent c43c832 commit 84c5a46

9 files changed

+178
-30
lines changed

‎README.md

+21-20
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,24 @@
11
# Python Fire
2-
_Python Fire is a library for creating command line interfaces (CLIs) from
3-
absolutely any Python object._
2+
_Python Fire is a library for automatically generating command line interfaces
3+
(CLIs) from absolutely any Python object._
44

5-
- Python Fire is a simple way to create a CLI in Python. [[1]](doc/benefits.md#simple-cli)
6-
- Python Fire is a helpful tool for developing and debugging Python code. [[2]](doc/benefits.md#debugging)
5+
- Python Fire is a simple way to create a CLI in Python. [[1]](docs/benefits.md#simple-cli)
6+
- Python Fire is a helpful tool for developing and debugging Python code. [[2]](docs/benefits.md#debugging)
77
- Python Fire helps with exploring existing code or turning other people's code
8-
into a CLI. [[3]](doc/benefits.md#exploring)
9-
- Python Fire makes transitioning between Bash and Python easier. [[4]](doc/benefits.md#bash)
8+
into a CLI. [[3]](docs/benefits.md#exploring)
9+
- Python Fire makes transitioning between Bash and Python easier. [[4]](docs/benefits.md#bash)
1010
- Python Fire makes using a Python REPL easier by setting up the REPL with the
11-
modules and variables you'll need already imported and created. [[5]](doc/benefits.md#repl)
11+
modules and variables you'll need already imported and created. [[5]](docs/benefits.md#repl)
1212

1313

1414
## Installation
1515

16-
`pip install fire`
16+
To install Python Fire with pip, run: `pip install fire`
1717

18-
OR
18+
To install Python Fire with conda, run: `conda install fire -c conda-forge`
1919

20-
`conda install fire -c conda-forge`
20+
To install Python Fire from source, first clone the repository and then run:
21+
`python setup.py install`
2122

2223

2324
## Basic Usage
@@ -26,7 +27,7 @@ You can call `Fire` on any Python object:<br>
2627
functions, classes, modules, objects, dictionaries, lists, tuples, etc.
2728
They all work!
2829

29-
Here's a simple example.
30+
Here's an example of calling Fire on a class.
3031

3132
```python
3233
import fire
@@ -49,9 +50,9 @@ python calculator.py double --number=15 # 30
4950
```
5051

5152
To learn how Fire behaves on functions, objects, dicts, lists, etc, and to learn
52-
about Fire's other features, see the [Using a Fire CLI page](doc/using-cli.md).
53+
about Fire's other features, see the [Using a Fire CLI page](docs/using-cli.md).
5354

54-
For additional examples, see [The Python Fire Guide](doc/guide.md).
55+
For additional examples, see [The Python Fire Guide](docs/guide.md).
5556

5657

5758
## Why is it called Fire?
@@ -61,7 +62,7 @@ When you call `Fire`, it fires off (executes) your command.
6162

6263
## Where can I learn more?
6364

64-
Please see [The Python Fire Guide](doc/guide.md).
65+
Please see [The Python Fire Guide](docs/guide.md).
6566

6667

6768
## Reference
@@ -78,12 +79,12 @@ Please see [The Python Fire Guide](doc/guide.md).
7879

7980
| Using a CLI | Command | Notes
8081
| :------------- | :------------------------- | :---------
81-
| [Help](doc/using-cli.md#help-flag) | `command -- --help` |
82-
| [REPL](doc/using-cli.md#interactive-flag) | `command -- --interactive` | Enters interactive mode.
83-
| [Separator](doc/using-cli.md#separator-flag) | `command -- --separator=X` | This sets the separator to `X`. The default separator is `-`.
84-
| [Completion](doc/using-cli.md#completion-flag) | `command -- --completion` | Generate a completion script for the CLI.
85-
| [Trace](doc/using-cli.md#trace-flag) | `command -- --trace` | Gets a Fire trace for the command.
86-
| [Verbose](doc/using-cli.md#verbose-flag) | `command -- --verbose` |
82+
| [Help](docs/using-cli.md#help-flag) | `command -- --help` |
83+
| [REPL](docs/using-cli.md#interactive-flag) | `command -- --interactive` | Enters interactive mode.
84+
| [Separator](docs/using-cli.md#separator-flag) | `command -- --separator=X` | This sets the separator to `X`. The default separator is `-`.
85+
| [Completion](docs/using-cli.md#completion-flag) | `command -- --completion` | Generate a completion script for the CLI.
86+
| [Trace](docs/using-cli.md#trace-flag) | `command -- --trace` | Gets a Fire trace for the command.
87+
| [Verbose](docs/using-cli.md#verbose-flag) | `command -- --verbose` |
8788

8889
_Note that flags are separated from the Fire command by an isolated `--` arg._
8990

‎docs/api.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
| Setup | Command | Notes
2+
| :------ | :------------------ | :---------
3+
| install | `pip install fire` |
4+
5+
| Creating a CLI | Command | Notes
6+
| :--------------| :--------------------- | :---------
7+
| import | `import fire` |
8+
| Call | `fire.Fire()` | Turns the current module into a Fire CLI.
9+
| Call | `fire.Fire(component)` | Turns `component` into a Fire CLI.
10+
11+
| Using a CLI | Command | Notes
12+
| :------------- | :------------------------- | :---------
13+
| [Help](using-cli.md#help-flag) | `command -- --help` |
14+
| [REPL](using-cli.md#interactive-flag) | `command -- --interactive` | Enters interactive mode.
15+
| [Separator](using-cli.md#separator-flag) | `command -- --separator=X` | This sets the separator to `X`. The default separator is `-`.
16+
| [Completion](using-cli.md#completion-flag) | `command -- --completion` | Generate a completion script for the CLI.
17+
| [Trace](using-cli.md#trace-flag) | `command -- --trace` | Gets a Fire trace for the command.
18+
| [Verbose](using-cli.md#verbose-flag) | `command -- --verbose` |
19+
20+
_Note that flags are separated from the Fire command by an isolated `--` arg._

‎doc/benefits.md renamed to ‎docs/benefits.md

+10-9
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
11
# Benefits of Python Fire
22

3-
## Python Fire is a simple way to create a CLI in Python. <a name="simple-cli"></a>
3+
<a name="simple-cli"></a>
4+
## Create CLIs in Python
45

56
It's dead simple. Simply write the functionality you want exposed at the command
67
line as a function / module / class, and then call Fire. With this addition of a
78
single-line call to Fire, your CLI is ready to go.
89

9-
10-
## Python Fire is a helpful tool for developing and debugging Python code. <a name="debugging"></a>
10+
<a name="debugging"></a>
11+
## Develop and debug Python code
1112

1213
When you're writing a Python library, you probably want to try it out as you go.
1314
You could write a main method to check the functionality you're interested in,
@@ -23,8 +24,8 @@ a main method. And if you use the `--interactive` flag to enter an IPython REPL
2324
then you don't need to load the imports or create your variables; they'll
2425
already be ready for use as soon as you start the REPL.
2526

26-
27-
## Python Fire helps with exploring existing code or turning other people's code into a CLI. <a name="exploring"></a>
27+
<a name="exploring"></a>
28+
## Explore existing code; turn other people's code into a CLI
2829

2930
You can take an existing module, maybe even one that you don't have access to
3031
the source code for, and call `Fire` on it. This lets you easily see what
@@ -40,8 +41,8 @@ The auto-generated help strings that Fire provides when you run a Fire CLI
4041
allow you to see all the functionality these modules provide in a concise
4142
manner.
4243

43-
44-
## Python Fire makes transitioning between Bash and Python easier. <a name="bash"></a>
44+
<a name="bash"></a>
45+
## Transition between Bash and Python
4546

4647
Using Fire lets you call Python directly from Bash. So you can mix your Python
4748
functions with the unix tools you know and love, like `grep`, `xargs`, `wc`,
@@ -51,8 +52,8 @@ Additionally since writing CLIs in Python requires only a single call to Fire,
5152
it is now easy to write even one-off scripts that would previously have been in
5253
Bash, in Python.
5354

54-
55-
## Python Fire makes using a Python REPL easier by setting up the REPL with the modules and variables you'll need already imported and created. <a name="repl"></a>
55+
<a name="repl"></a>
56+
## Explore code in a Python REPL
5657

5758
When you use the `--interactive` flag to enter an IPython REPL, it starts with
5859
variables and modules already defined for you. You don't need to waste time

‎doc/guide.md renamed to ‎docs/guide.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -489,7 +489,7 @@ $ python example.py --name="Sherrerd Hall" climb_stairs --stairs-per-story 10
489489
$ python example.py climb-stairs --stairs-per-story 10 --name="Sherrerd Hall"
490490
```
491491

492-
You'll notice that hyphens and underscores (`-` and `_`) are interchangable in
492+
You'll notice that hyphens and underscores (`-` and `_`) are interchangeable in
493493
member names and flag names.
494494

495495
You'll also notice that the constructor's arguments can come after the

‎docs/index.md

+94
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Python Fire
2+
_Python Fire is a library for automatically generating command line interfaces
3+
(CLIs) from absolutely any Python object._
4+
5+
- Python Fire is a simple way to create a CLI in Python. [[1]](benefits.md#simple-cli)
6+
- Python Fire is a helpful tool for developing and debugging Python code. [[2]](benefits.md#debugging)
7+
- Python Fire helps with exploring existing code or turning other people's code
8+
into a CLI. [[3]](benefits.md#exploring)
9+
- Python Fire makes transitioning between Bash and Python easier. [[4]](benefits.md#bash)
10+
- Python Fire makes using a Python REPL easier by setting up the REPL with the
11+
modules and variables you'll need already imported and created. [[5]](benefits.md#repl)
12+
13+
14+
## Installation
15+
16+
To install Python Fire with pip, run: `pip install fire`
17+
18+
To install Python Fire with conda, run: `conda install fire -c conda-forge`
19+
20+
To install Python Fire from source, first clone the repository and then run:
21+
`python setup.py install`
22+
23+
24+
## Basic Usage
25+
26+
You can call `Fire` on any Python object:<br>
27+
functions, classes, modules, objects, dictionaries, lists, tuples, etc.
28+
They all work!
29+
30+
Here's an example of calling Fire on a class.
31+
32+
```python
33+
import fire
34+
35+
class Calculator(object):
36+
"""A simple calculator class."""
37+
38+
def double(self, number):
39+
return 2 * number
40+
41+
if __name__ == '__main__':
42+
fire.Fire(Calculator)
43+
```
44+
45+
Then, from the command line, you can run:
46+
47+
```bash
48+
python calculator.py double 10 # 20
49+
python calculator.py double --number=15 # 30
50+
```
51+
52+
To learn how Fire behaves on functions, objects, dicts, lists, etc, and to learn
53+
about Fire's other features, see the [Using a Fire CLI page](using-cli.md).
54+
55+
For additional examples, see [The Python Fire Guide](guide.md).
56+
57+
58+
## Why is it called Fire?
59+
60+
When you call `Fire`, it fires off (executes) your command.
61+
62+
63+
## Where can I learn more?
64+
65+
Please see [The Python Fire Guide](guide.md).
66+
67+
68+
## Reference
69+
70+
| Setup | Command | Notes
71+
| :------ | :------------------ | :---------
72+
| install | `pip install fire` |
73+
74+
| Creating a CLI | Command | Notes
75+
| :--------------| :--------------------- | :---------
76+
| import | `import fire` |
77+
| Call | `fire.Fire()` | Turns the current module into a Fire CLI.
78+
| Call | `fire.Fire(component)` | Turns `component` into a Fire CLI.
79+
80+
| Using a CLI | Command | Notes
81+
| :------------- | :------------------------- | :---------
82+
| [Help](using-cli.md#help-flag) | `command -- --help` |
83+
| [REPL](using-cli.md#interactive-flag) | `command -- --interactive` | Enters interactive mode.
84+
| [Separator](using-cli.md#separator-flag) | `command -- --separator=X` | This sets the separator to `X`. The default separator is `-`.
85+
| [Completion](using-cli.md#completion-flag) | `command -- --completion` | Generate a completion script for the CLI.
86+
| [Trace](using-cli.md#trace-flag) | `command -- --trace` | Gets a Fire trace for the command.
87+
| [Verbose](using-cli.md#verbose-flag) | `command -- --verbose` |
88+
89+
_Note that flags are separated from the Fire command by an isolated `--` arg._
90+
91+
92+
## Disclaimer
93+
94+
This is not an official Google product.

‎docs/installation.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Installation
2+
3+
To install Python Fire with pip, run: `pip install fire`
4+
5+
To install Python Fire with conda, run: `conda install fire -c conda-forge`
6+
7+
To install Python Fire from source, first clone the repository and then run:
8+
`python setup.py install`

‎docs/troubleshooting.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Troubleshooting
2+
3+
This page describes known issues that users of Python Fire have run into. If you
4+
have an issue not resolved here, consider opening a
5+
[GitHub Issue](https://github.com/google/python-fire/issues).
6+
7+
### Issue [#19](https://github.com/google/python-fire/issues/19): Don't name your module "cmd"
8+
9+
If you have a module name that conflicts with the name of a builtin module, then
10+
when Fire goes to import the builtin module, it will import your module instead.
11+
This will result in an error, possibly an `AttributeError`. Specifically, do not
12+
name your module any of the following:
13+
sys, linecache, cmd, bdb, repr, os, re, pprint, traceback

‎doc/using-cli.md renamed to ‎docs/using-cli.md

File renamed without changes.

‎mkdocs.yml

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
site_name: Python Fire
2+
theme: readthedocs
3+
markdown_extensions: [fenced_code]
4+
pages:
5+
- Overview: index.md
6+
- Installation: installation.md
7+
- Benefits: benefits.md
8+
- The Python Fire Guide: guide.md
9+
- Using a CLI: using-cli.md
10+
- Troubleshooting: troubleshooting.md
11+
- Reference: api.md

0 commit comments

Comments
 (0)