📝 Update docs to use Typer() more prominently
#1418
Conversation
| {* docs_src/arguments/optional/tutorial000.py hl[4] *} | ||
|
|
||
| {* docs_src/arguments/optional/tutorial001_an.py hl[5] *} | ||
| Or, using an explicit `Typer()` instance creation: | ||
|
|
||
| {* docs_src/arguments/optional/tutorial001_an.py hl[8] *} |
There was a problem hiding this comment.
Here, I've created a new tutorial file (docs_src/arguments/optional/tutorial000.py) to better show the difference with the more simplistic docs_src/first_steps/tutorial002.py. The next version then (docs_src/arguments/optional/tutorial001_an.py) introduces both Annotated as well as Typer().
| {* docs_src/arguments/optional/tutorial003.py hl[7] *} | ||
|
|
||
| And the same way, you can make it optional by passing a different `default` value, for example `None`: | ||
| And the same way, you can make it optional by passing a different `default` value, for example `"World"`: |
There was a problem hiding this comment.
Here, and in the lines below, I've had to make extra edits, because this section had become out-of-date on master after PR #983. Basically in PR 983 we updated tutorial002 to have the default value "World" instead of None, and we updated the explanation around L112 but didn't notice that this same example was being used here at the end of the page at L220 and beyond.
|
|
||
| Here I'll use **CLI application** or **program** to refer to the program you are building in Python with Typer, and **command** to refer to one of these "subcommands" of your program. | ||
|
|
||
| ## Explicit application |
There was a problem hiding this comment.
This bit is moved almost verbatim to typer-instance.md, with some minor edits to ensure correct flow.
| @@ -0,0 +1,116 @@ | |||
| ## Explicit application | |||
There was a problem hiding this comment.
Now, the title of this page is "Typer instance" - we should decide whether this is what we want, or something else.
docs/tutorial/exceptions.md
Outdated
| <font color="#F92672">│</font> 7 <font color="#F92672">│</font> | ||
| <font color="#F92672">│</font> 8 <font color="#66D9EF">if</font> <font color="#F92672">__name__</font> == <font color="#F4BF75">"__main__"</font>: <font color="#F92672">│</font> | ||
| <font color="#F92672">│</font> 5 <font color="#F92672">│</font> | ||
| <font color="#F92672">│</font> 6 <font color="#FF00FF">@app</font>.command() <font color="#F92672">│</font> |
There was a problem hiding this comment.
TODO: outline this correctly 🙈
There was a problem hiding this comment.
This looks fine now, though this was mostly edited manually CC @tiangolo
| And then calling the `.update()` method in the object from the `with` statement: | ||
|
|
||
| {* docs_src/progressbar/tutorial006.py hl[8,12] *} | ||
| {* docs_src/progressbar/tutorial006.py hl[11,17] *} |
There was a problem hiding this comment.
This one was wrong on master:
And is now fixed:
svlandeg
left a comment
svlandeg
left a comment
There was a problem hiding this comment.
Ok, this should be now in a good state.
Searching through the code base, the only places that still refer to typer.run() are
- the "first steps" part of the tutorial
docs_src/arguments/optional/tutorial000.pywhich was created in this PR specifically to gradually build up the complexity in the "Arguments" docs sectiondocs_src/testing/app03which specifically talks about testing code that don't useTyper()
Everything else is now converted to Typer() and all highlighting in the documentation has been updated, including a few fixes of things that weren't exactly right on master (made separate comments about these).
1 participant
In an attempt to be minimal/clear, the docs have mostly been using
typer.run. However for proper applications, we recommend to useTyper()directly, which unlocks much more options. As such, we're updating the docs here. This has the added advantage that it's easier to experiment with given tutorial examples without first having to adjust them to useTyper().I know reviewing this is horrible. I've taken the time to go through every edit carefully (0% vibe coding ;-)). Mostly, this meant updating the tutorial examples and then updating the highlighted lines in the documentation markdown files. There were some special cases, that I'll highlight as review comments.