From 2af83b0be5309ce67a513cbd10318f15a2db0078 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Sat, 18 Jan 2020 19:35:49 +0100 Subject: [PATCH] :memo: Refactor docs with internal links --- README.md | 4 ++-- docs/contributing.md | 2 +- docs/css/custom.css | 12 +++++++++++- docs/features.md | 6 +++--- docs/index.md | 4 ++-- docs/tutorial/arguments.md | 4 ++-- docs/tutorial/first-steps.md | 4 ++-- docs/tutorial/index.md | 2 +- docs/tutorial/prompt.md | 4 ++-- docs/tutorial/subcommands/callback-override.md | 2 +- docs/tutorial/subcommands/index.md | 2 +- 11 files changed, 28 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index bbbb9ce..ec348c8 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Typer is library to build CLI applications that users will love using and developers will love creating. Based on Python 3.6+ type hints. -**Typer** is FastAPI's little sibling. And it's intended to be the FastAPI of CLIs. +**Typer** is FastAPI's little sibling. And it's intended to be the FastAPI of CLIs. The key features are: @@ -243,7 +243,7 @@ And similarly for **files**, **paths**, **enums** (choices), etc. And there are **Your users get**: automatic **`--help`**, (optional) **autocompletion** in their terminal (Bash, Zsh, Fish, PowerShell). -For a more complete example including more features, see the Tutorial - User Guide. +For a more complete example including more features, see the Tutorial - User Guide. ## Optional Dependencies diff --git a/docs/contributing.md b/docs/contributing.md index 4e16039..a97ddae 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,4 +1,4 @@ -First, you might want to see the basic ways to help Typer and get help. +First, you might want to see the basic ways to [help Typer and get help](help-typer.md){.internal-link target=_blank}. Coming soon... diff --git a/docs/css/custom.css b/docs/css/custom.css index 735128c..954b0cf 100644 --- a/docs/css/custom.css +++ b/docs/css/custom.css @@ -9,5 +9,15 @@ } a.external-link::after { - content: " [↪]"; + /* \00A0 is a non-breaking space + to make the mark be on the same line as the link + */ + content: "\00A0[↪]"; +} + +a.internal-link::after { + /* \00A0 is a non-breaking space + to make the mark be on the same line as the link + */ + content: "\00A0↪"; } diff --git a/docs/features.md b/docs/features.md index 08139cf..e2dde85 100644 --- a/docs/features.md +++ b/docs/features.md @@ -1,6 +1,6 @@ ## Design based on **FastAPI** -**Typer** is FastAPI's little sibling. +**Typer** is FastAPI's little sibling. It follows the same design and ideas. If you know FastAPI, you already know **Typer**... more or less. @@ -8,9 +8,9 @@ It follows the same design and ideas. If you know FastAPI, you already know **Ty It's all based on standard **Python 3.6 type** declarations. No new syntax to learn. Just standard modern Python. -If you need a 2 minute refresher of how to use Python types (even if you don't use FastAPI or Typer), check the FastAPI tutorial section: Python types intro. +If you need a 2 minute refresher of how to use Python types (even if you don't use FastAPI or Typer), check the FastAPI tutorial section: Python types intro. -You will also see a 20 seconds refresher on the section [Tutorial - User Guide: First Steps](tutorial/first-steps.md). +You will also see a 20 seconds refresher on the section [Tutorial - User Guide: First Steps](tutorial/first-steps.md){.internal-link target=_blank}. ## Editor support diff --git a/docs/index.md b/docs/index.md index bbbb9ce..ec348c8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,7 +26,7 @@ Typer is library to build CLI applications that users will love using and developers will love creating. Based on Python 3.6+ type hints. -**Typer** is FastAPI's little sibling. And it's intended to be the FastAPI of CLIs. +**Typer** is FastAPI's little sibling. And it's intended to be the FastAPI of CLIs. The key features are: @@ -243,7 +243,7 @@ And similarly for **files**, **paths**, **enums** (choices), etc. And there are **Your users get**: automatic **`--help`**, (optional) **autocompletion** in their terminal (Bash, Zsh, Fish, PowerShell). -For a more complete example including more features, see the Tutorial - User Guide. +For a more complete example including more features, see the Tutorial - User Guide. ## Optional Dependencies diff --git a/docs/tutorial/arguments.md b/docs/tutorial/arguments.md index c9c1940..66c4886 100644 --- a/docs/tutorial/arguments.md +++ b/docs/tutorial/arguments.md @@ -35,7 +35,7 @@ __init__.py test_tutorial ### An alternative *CLI argument* declaration -In the First Steps you saw how to add a *CLI argument*: +In the [First Steps](first-steps.md#add-a-cli-argument){.internal-link target=_blank} you saw how to add a *CLI argument*: ```Python hl_lines="4" {!./src/first_steps/tutorial002.py!} @@ -191,7 +191,7 @@ For that reason, Typer (actually Click underneath) doesn't attempt to automatica And you should document them as part of the CLI app documentation, normally in a docstring. -Check the last example from the First Steps: +Check the last example from the [First Steps](first-steps.md#document-your-cli-app){.internal-link target=_blank}: ```Python hl_lines="5 6 7 8 9" {!./src/first_steps/tutorial006.py!} diff --git a/docs/tutorial/first-steps.md b/docs/tutorial/first-steps.md index e8c2ffa..5ce8b52 100644 --- a/docs/tutorial/first-steps.md +++ b/docs/tutorial/first-steps.md @@ -389,14 +389,14 @@ are called "Python function parameters" or "Python function arguments". One refers to the variable name in a function *declaration*. Like: - ```Python + ``` def bring_person(name: str, lastname: str = ""): pass ``` The other refers to the value passed when *calling* a function. Like: - ```Python + ``` person = bring_person("Camila", lastname="Gutiérrez") ``` diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index 084f68a..c288691 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -1,6 +1,6 @@ ## Python types -If you need a refreshed about how to use Python type hints, check the first part of FastAPI's Python types intro. +If you need a refreshed about how to use Python type hints, check the first part of FastAPI's Python types intro. You can also check the mypy cheat sheet. diff --git a/docs/tutorial/prompt.md b/docs/tutorial/prompt.md index 56c5846..2c38f8f 100644 --- a/docs/tutorial/prompt.md +++ b/docs/tutorial/prompt.md @@ -1,4 +1,4 @@ -When you need to ask the user for info interactively you should normally use *CLI Option*s with Prompt, because they allow using the CLI program in a non-interactive way (for example, a Bash script could use it). +When you need to ask the user for info interactively you should normally use [*CLI Option*s with Prompt](options/prompt.md){.internal-link target=_blank}, because they allow using the CLI program in a non-interactive way (for example, a Bash script could use it). But if you absolutely need to ask for interactive information without using a *CLI option*, you can use `typer.prompt()`: @@ -22,7 +22,7 @@ Hello Camila ## Confirm -There's also an alternative to ask for confirmation. Again, if possible, you should use a *CLI Option* with a confirmation prompt: +There's also an alternative to ask for confirmation. Again, if possible, you should use a [*CLI Option* with a confirmation prompt](options/prompt.md){.internal-link target=_blank}: ```Python hl_lines="5" {!./src/prompt/tutorial002.py!} diff --git a/docs/tutorial/subcommands/callback-override.md b/docs/tutorial/subcommands/callback-override.md index 3c8c788..e419b9e 100644 --- a/docs/tutorial/subcommands/callback-override.md +++ b/docs/tutorial/subcommands/callback-override.md @@ -51,7 +51,7 @@ Creating user: Camila If a callback was added when creating the `typer.Typer()` app, it's possible to override it with a new one using `@app.callback()`. -This is the same information you saw on the section about Commands - Typer Callback, and it applies the same for sub-Typer apps: +This is the same information you saw on the section about [Commands - Typer Callback](../commands/callback.md){.internal-link target=_blank}, and it applies the same for sub-Typer apps: ```Python hl_lines="6 7 10 14 15 16" {!./src/subcommands/callback_override/tutorial003.py!} diff --git a/docs/tutorial/subcommands/index.md b/docs/tutorial/subcommands/index.md index f1b6fb0..5a8df35 100644 --- a/docs/tutorial/subcommands/index.md +++ b/docs/tutorial/subcommands/index.md @@ -1,4 +1,4 @@ -You read before how to create a program with Commands. +You read before how to create a program with [Commands](../commands/index.md){.internal-link target=_blank}. Now we'll see how to create a *CLI program* with commands that have their own subcommands. Also known as command groups.