Merge branch 'master' into fix/rich_none

.github/workflows/build-docs.yml

@@ -18,7 +18,7 @@ jobs:
       docs: ${{ steps.filter.outputs.docs }}
     steps:
     - uses: actions/checkout@v4
-    # For pull requests it's not necessary to checkout the code but for master it is
+    # For pull requests it's not necessary to checkout the code but for the main branch it is
     - uses: dorny/paths-filter@v3
       id: filter
       with:
@@ -28,9 +28,12 @@ jobs:
             - docs/**
             - docs_src/**
             - requirements-docs.txt
+            - requirements-docs-insiders.txt
             - pyproject.toml
             - mkdocs.yml
             - mkdocs.insiders.yml
+            - mkdocs.maybe-insiders.yml
+            - mkdocs.no-insiders.yml
             - .github/workflows/build-docs.yml
             - .github/workflows/deploy-docs.yml
 
@@ -53,16 +56,15 @@ jobs:
         id: cache
         with:
           path: ${{ env.pythonLocation }}
-          key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt') }}-v02
+          key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt', 'requirements-docs-insiders.txt') }}-v02
       - name: Install docs extras
         if: steps.cache.outputs.cache-hit != 'true'
         run: pip install -r requirements-docs.txt
       - name: Install Material for MkDocs Insiders
         if: ( github.event_name != 'pull_request' || github.secret_source == 'Actions' ) && steps.cache.outputs.cache-hit != 'true'
-        run: |
-          pip install git+https://${{ secrets.TYPER_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
-          pip install git+https://${{ secrets.TYPER_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/griffe-typing-deprecated.git
-          pip install git+https://${{ secrets.TYPER_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/mkdocstrings-python.git
+        run: pip install -r requirements-docs-insiders.txt
+        env:
+          TOKEN: ${{ secrets.TYPER_MKDOCS_MATERIAL_INSIDERS }}
       - uses: actions/cache@v4
         with:
           key: mkdocs-cards-${{ github.ref }}-v1

.github/workflows/deploy-docs.yml

@@ -10,6 +10,7 @@ permissions:
   deployments: write
   issues: write
   pull-requests: write
+  statuses: write
 
 jobs:
   deploy-docs:
@@ -20,6 +21,25 @@ jobs:
           GITHUB_CONTEXT: ${{ toJson(github) }}
         run: echo "$GITHUB_CONTEXT"
       - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: actions/cache@v4
+        id: cache
+        with:
+          path: ${{ env.pythonLocation }}
+          key: ${{ runner.os }}-python-github-actions-${{ env.pythonLocation }}-${{ hashFiles('requirements-github-actions.txt') }}-v01
+      - name: Install GitHub Actions dependencies
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: pip install -r requirements-github-actions.txt
+      - name: Deploy Docs Status Pending
+        run: python ./scripts/deploy_docs_status.py
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMMIT_SHA: ${{ github.event.workflow_run.head_sha }}
+          RUN_ID: ${{ github.run_id }}
+
       - name: Clean site
         run: |
           rm -rf ./site
@@ -43,22 +63,11 @@ jobs:
           directory: './site'
           gitHubToken: ${{ secrets.GITHUB_TOKEN }}
           branch: ${{ ( github.event.workflow_run.head_repository.full_name == github.repository && github.event.workflow_run.head_branch == 'master' && 'main' ) || ( github.event.workflow_run.head_sha ) }}
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-      - uses: actions/cache@v4
-        id: cache
-        with:
-          path: ${{ env.pythonLocation }}
-          key: ${{ runner.os }}-python-github-actions-${{ env.pythonLocation }}-${{ hashFiles('requirements-github-actions.txt') }}-v01
-      - name: Install GitHub Actions dependencies
-        if: steps.cache.outputs.cache-hit != 'true'
-        run: pip install -r requirements-github-actions.txt
       - name: Comment Deploy
-        if: steps.deploy.outputs.url != ''
-        run: python ./scripts/comment_docs_deploy_url_in_pr.py
+        run: python ./scripts/deploy_docs_status.py
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           DEPLOY_URL: ${{ steps.deploy.outputs.url }}
           COMMIT_SHA: ${{ github.event.workflow_run.head_sha }}
+          RUN_ID: ${{ github.run_id }}
+          IS_DONE: "true"

.github/workflows/test-redistribute.yml

@@ -57,3 +57,15 @@ jobs:
         run: |
           cd dist
           pip wheel --no-deps typer*.tar.gz
+
+  # https://github.com/marketplace/actions/alls-green#why
+  test-redistribute-alls-green:  # This job does nothing and is only used for the branch protection
+    if: always()
+    needs:
+      - test-redistribute
+    runs-on: ubuntu-latest
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@release/v1
+        with:
+          jobs: ${{ toJSON(needs) }}

docs/alternatives.md

@@ -1,3 +1,5 @@
+# Alternatives, Inspiration and Comparisons
+
 What inspired **Typer**, how it compares to other alternatives and what it learned from them.
 
 ## Intro

docs/contributing.md

@@ -1,3 +1,5 @@
+# Development - Contributing
+
 First, you might want to see the basic ways to [help Typer and get help](help-typer.md){.internal-link target=_blank}.
 
 ## Developing

docs/css/termynal.css

@@ -26,6 +26,7 @@
     position: relative;
     -webkit-box-sizing: border-box;
             box-sizing: border-box;
+    /* Custom line-height */
     line-height: 1.2;
 }
 

docs/features.md

@@ -1,3 +1,5 @@
+# Features
+
 ## Design based on **FastAPI**
 
 <a href="https://fastapi.tiangolo.com" target="_blank"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" style="width: 20%;"></a>

docs/help-typer.md

@@ -1,3 +1,5 @@
+# Help Typer - Get Help
+
 Are you liking **Typer**?
 
 Would you like to help Typer, other users, and the author?

docs/js/custom.js

@@ -110,4 +110,6 @@ async function main() {
     setupTermynal()
 }
 
-main()
+document$.subscribe(() => {
+    main()
+})

docs/js/termynal.js

@@ -249,7 +249,6 @@ class Termynal {
                 attrs += `${this.pfx}-${prop}="${line[prop]}" `
             }
         }
-
         return attrs;
     }
 }

docs/release-notes.md

@@ -1,3 +1,5 @@
+# Release Notes
+
 ## Latest Changes
 
 ### Features
@@ -6,6 +8,11 @@
 
 ### Internal
 
+* 👷 Upgrade build docs configs. PR [#914](https://github.com/tiangolo/typer/pull/914) by [@tiangolo](https://github.com/tiangolo).
+* 🔧 Update MkDocs to have titles in Markdown files instead of config. PR [#913](https://github.com/tiangolo/typer/pull/913) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Add alls-green for test-redistribute. PR [#911](https://github.com/tiangolo/typer/pull/911) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Update docs-previews to handle no docs changes. PR [#912](https://github.com/tiangolo/typer/pull/912) by [@tiangolo](https://github.com/tiangolo).
+* 👷🏻 Show docs deployment status and preview URLs in comment. PR [#910](https://github.com/tiangolo/typer/pull/910) by [@tiangolo](https://github.com/tiangolo).
 * 🔧 Enable auto dark mode from system. PR [#908](https://github.com/tiangolo/typer/pull/908) by [@tiangolo](https://github.com/tiangolo).
 * 💄 Add dark mode logo. PR [#907](https://github.com/tiangolo/typer/pull/907) by [@tiangolo](https://github.com/tiangolo).
 * 🔧 Update tabs and admonitions with new syntax and new MkDocs features. PR [#906](https://github.com/tiangolo/typer/pull/906) by [@tiangolo](https://github.com/tiangolo).

docs/tutorial/app-dir.md

@@ -1,3 +1,5 @@
+# CLI Application Directory
+
 You can get the application directory where you can, for example, save configuration files with `typer.get_app_dir()`:
 
 ```Python hl_lines="9"

docs/tutorial/arguments/default.md

@@ -1,3 +1,5 @@
+# CLI Arguments with Default
+
 We can also use the same `typer.Argument()` to set a default value.
 
 That way the *CLI argument* will be optional *and also* have a default value.

docs/tutorial/arguments/envvar.md

@@ -1,3 +1,5 @@
+# CLI Arguments with Environment Variables
+
 You can also configure a *CLI argument* to read a value from an environment variable if it is not provided in the command line as a *CLI argument*.
 
 To do that, use the `envvar` parameter for `typer.Argument()`:

docs/tutorial/arguments/help.md

@@ -1,3 +1,5 @@
+# CLI Arguments with Help
+
 In the *First Steps* section you saw how to add help for a CLI app/command by adding it to a function's <abbr title="a multi-line string as the first expression inside a function (not assigned to any variable) used for documentation">docstring</abbr>.
 
 Here's how that last example looked like:

docs/tutorial/arguments/index.md

@@ -1,3 +1,5 @@
+# CLI Arguments
+
 In the next few sections we'll see some ways to modify how *CLI arguments* work.
 
 We'll create optional *CLI arguments*, we'll add integrated help for *CLI arguments*, etc.

docs/tutorial/arguments/optional.md

@@ -1,3 +1,5 @@
+# Optional CLI Arguments
+
 We said before that *by default*:
 
 * *CLI options* are **optional**

docs/tutorial/arguments/other-uses.md

@@ -1,3 +1,5 @@
+# Other uses
+
 `typer.Argument()` has several other use cases. Such as for data validation, to enable other features, etc.
 
 You will see about these use cases later in the docs.

docs/tutorial/commands/arguments.md

@@ -1,3 +1,5 @@
+# Command CLI Arguments
+
 The same way as with a CLI application with a single command, subcommands (or just "commands") can also have their own *CLI arguments*:
 
 ```Python hl_lines="7  12"

docs/tutorial/commands/callback.md

@@ -1,3 +1,5 @@
+# Typer Callback
+
 When you create an `app = typer.Typer()` it works as a group of commands.
 
 And you can create multiple commands with it.

docs/tutorial/commands/context.md

@@ -1,3 +1,5 @@
+# Using the Context
+
 When you create a **Typer** application it uses Click underneath. And every Click application has a special object called a <a href="https://click.palletsprojects.com/en/8.1.x/commands/#nested-handling-and-contexts" class="external-link" target="_blank">"Context"</a> that is normally hidden.
 
 But you can access the context by declaring a function parameter of type `typer.Context`.

docs/tutorial/commands/help.md

@@ -1,3 +1,5 @@
+# Command Help
+
 The same as before, you can add help for the commands in the docstrings and the *CLI options*.
 
 And the `typer.Typer()` application receives a parameter `help` that you can pass with the main help text for your CLI program:

docs/tutorial/commands/index.md

@@ -1,3 +1,5 @@
+# Commands
+
 We have seen how to create a CLI program with possibly several *CLI options* and *CLI arguments*.
 
 But **Typer** allows you to create CLI programs with several commands (also known as subcommands).

docs/tutorial/commands/name.md

@@ -1,3 +1,5 @@
+# Custom Command Name
+
 By default, the command names are generated from the function name.
 
 So, if your function is something like:

docs/tutorial/commands/one-or-multiple.md

@@ -1,3 +1,5 @@
+# One or Multiple Commands
+
 You might have noticed that if you create a single command, as in the first example:
 
 ```Python hl_lines="3  6  12"

docs/tutorial/commands/options.md

@@ -1,3 +1,5 @@
+# Command CLI Options
+
 Commands can also have their own *CLI options*.
 
 In fact, each command can have different *CLI arguments* and *CLI options*:

docs/tutorial/first-steps.md

@@ -1,3 +1,5 @@
+# First Steps
+
 ## The simplest example
 
 The simplest **Typer** file could look like this:

docs/tutorial/index.md

@@ -1,3 +1,5 @@
+# Tutorial - User Guide
+
 ## Python types
 
 If you need a refresher about how to use Python type hints, check the first part of <a href="https://fastapi.tiangolo.com/python-types/" class="external-link" target="_blank">FastAPI's Python types intro</a>.

docs/tutorial/launch.md

@@ -1,3 +1,5 @@
+# Launching Applications
+
 You can launch applications from your CLI program with `typer.launch()`.
 
 It will launch the appropriate application depending on the URL or file type you pass it:

docs/tutorial/multiple-values/arguments-with-multiple-values.md

@@ -1,3 +1,5 @@
+# CLI Arguments with Multiple Values
+
 *CLI arguments* can also receive multiple values.
 
 You can define the type of a *CLI argument* using `typing.List`.

docs/tutorial/multiple-values/index.md

@@ -1,3 +1,5 @@
+# Multiple Values
+
 There are several ways to declare multiple values for *CLI options* and *CLI arguments*.
 
 We'll see them in the next short sections.

docs/tutorial/multiple-values/multiple-options.md

@@ -1,3 +1,5 @@
+# Multiple CLI Options
+
 You can declare a *CLI option* that can be used multiple times, and then get all the values.
 
 For example, let's say you want to accept several users in a single execution.

docs/tutorial/multiple-values/options-with-multiple-values.md

@@ -1,3 +1,5 @@
+# CLI Options with Multiple Values
+
 You can also declare a *CLI option* that takes several values of different types.
 
 You can set the number of values and types to anything you want, but it has to be a fixed number of values.

docs/tutorial/options-autocompletion.md

@@ -1,3 +1,5 @@
+# CLI Option autocompletion
+
 As you have seen, apps built with **Typer** have completion in your shell that works when you create a Python package or using the `typer` command.
 
 It normally completes *CLI options*, *CLI arguments*, and subcommands (that you will learn about later).

docs/tutorial/options/callback-and-context.md

@@ -1,3 +1,5 @@
+# CLI Option Callback and Context
+
 In some occasions you might want to have some custom logic for a specific *CLI parameter* (for a *CLI option*  or *CLI argument*) that is executed with the value received from the terminal.
 
 In those cases you can use a *CLI parameter* callback function.

docs/tutorial/options/help.md

@@ -1,3 +1,5 @@
+# CLI Options with Help
+
 You already saw how to add a help text for *CLI arguments* with the `help` parameter.
 
 Let's now do the same for *CLI options*:

docs/tutorial/options/index.md

@@ -1,3 +1,5 @@
+# CLI Options
+
 In the next short sections we will see how to modify *CLI options* using `typer.Option()`.
 
 `typer.Option()` works very similarly to `typer.Argument()`, but has some extra features that we'll see next.

docs/tutorial/options/name.md

@@ -1,3 +1,5 @@
+# CLI Option Name
+
 By default **Typer** will create a *CLI option* name from the function parameter.
 
 So, if you have a function with:

docs/tutorial/options/password.md

@@ -1,3 +1,5 @@
+# Password CLI Option and Confirmation Prompt
+
 Apart from having a prompt, you can make a *CLI option* have a `confirmation_prompt=True`:
 
 //// tab | Python 3.7+

docs/tutorial/options/prompt.md

@@ -1,3 +1,5 @@
+# CLI Option Prompt
+
 It's also possible to, instead of just showing an error, ask for the missing value with `prompt=True`:
 
 //// tab | Python 3.7+

docs/tutorial/options/required.md

@@ -1,3 +1,5 @@
+# Required CLI Options
+
 We said before that *by default*:
 
 * *CLI options* are **optional**

docs/tutorial/options/version.md

@@ -1,3 +1,5 @@
+# Version CLI Option, `is_eager`
+
 You could use a callback to implement a `--version` *CLI option*.
 
 It would show the version of your CLI program and then it would terminate it. Even before any other *CLI parameter* is processed.

docs/tutorial/package.md

@@ -1,3 +1,5 @@
+# Building a Package
+
 When you create a CLI program with **Typer** you probably want to create your own Python package.
 
 That's what allows your users to install it and have it as an independent program that they can use in their terminal.

docs/tutorial/parameter-types/bool.md

@@ -1,3 +1,5 @@
+# Boolean CLI Options
+
 We have seen some examples of *CLI options* with `bool`, and how **Typer** creates `--something` and `--no-something` automatically.
 
 But we can customize those names.

docs/tutorial/parameter-types/custom-types.md

@@ -1,3 +1,5 @@
+# Custom Types
+
 You can easily use your own custom types in your **Typer** applications.
 
 The way to do it is by providing a way to <abbr title="convert from some plain format, like the input text in the CLI, into Python objects">parse</abbr> input into your own types.

docs/tutorial/parameter-types/datetime.md

@@ -1,3 +1,5 @@
+# DateTime
+
 You can specify a *CLI parameter* as a Python <a href="https://docs.python.org/3/library/datetime.html" class="external-link" target="_blank">`datetime`</a>.
 
 Your function will receive a standard Python `datetime` object, and again, your editor will give you completion, etc.