📝 Add reference (code API) docs (#1504)

Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
Co-authored-by: Sebastián Ramírez <tiangolo@gmail.com>

Author: 3 people

docs/reference/context.md

@@ -0,0 +1,38 @@
+# Context
+
+When you create a Typer application it uses Click underneath.
+And every Click application has a special object called a [`Context`](https://click.palletsprojects.com/en/stable/api/#click.Context) that is normally hidden.
+But you can access the context by declaring a function parameter of type `typer.Context`.
+
+The same way you can access the context by declaring a function parameter with its value,
+you can declare another function parameter with type `typer.CallbackParam` to get the specific Click [`Parameter`](https://click.palletsprojects.com/en/stable/api/#click.Parameter) object.
+
+```python
+from typing import Annotated
+
+import typer
+
+app = typer.Typer()
+
+
+def name_callback(ctx: typer.Context, param: typer.CallbackParam, value: str):
+    if ctx.resilient_parsing:
+        return
+    print(f"Validating param: {param.name}")
+    if value != "Rick":
+        raise typer.BadParameter("Only Rick is allowed")
+    return value
+
+
+@app.command()
+def main(name: Annotated[str | None, typer.Option(callback=name_callback)] = None):
+    print(f"Hello {name}")
+
+
+if __name__ == "__main__":
+    app()
+```
+
+::: typer.Context
+
+::: typer.CallbackParam

docs/reference/file_objects.md

@@ -0,0 +1,18 @@
+# File objects
+
+When you want to declare some types of files, you can use `Path`.
+However, in some cases you may need to have access to a file-like object, and then you can use these [special File types](https://typer.tiangolo.com/tutorial/parameter-types/file/).
+
+These objects can be imported from `typer` directly:
+
+```python
+from typer import FileBinaryRead, FileBinaryWrite, FileText, FileTextWrite
+```
+
+::: typer.FileText
+
+::: typer.FileTextWrite
+
+::: typer.FileBinaryRead
+
+::: typer.FileBinaryWrite

docs/reference/index.md

@@ -0,0 +1,7 @@
+# Reference
+
+Here's the reference or code API, the classes, functions, parameters, attributes, and
+all the Typer parts you can use in your applications.
+
+If you want to **learn Typer** you are much better off reading the
+[Typer Tutorial](https://typer.tiangolo.com/tutorial/).

docs/reference/parameters.md

@@ -0,0 +1,31 @@
+# Parameters
+
+Parameters to our command line interface may be both [CLI Options](https://typer.tiangolo.com/tutorial/options/) and [CLI Arguments](https://typer.tiangolo.com/tutorial/arguments/):
+
+```python
+from typing import Annotated
+import typer
+
+app = typer.Typer()
+
+@app.command()
+def register(
+    user: Annotated[str, typer.Argument()],
+    age: Annotated[int, typer.Option(min=18)],
+    score: Annotated[float, typer.Option(max=100)] = 0,
+):
+    print(f"User is {user}")
+    print(f"--age is {age}")
+    print(f"--score is {score}")
+
+if __name__ == "__main__":
+    app()
+```
+
+::: typer.Argument
+    options:
+      show_overloads: false
+
+::: typer.Option
+    options:
+      show_overloads: false

docs/reference/run_launch.md

@@ -0,0 +1,11 @@
+# `run` and `launch`
+
+These two functions can be imported from `typer` directly:
+
+```python
+from typer import launch, run
+```
+
+::: typer.run
+
+::: typer.launch

docs/reference/typer.md

@@ -0,0 +1,16 @@
+# `Typer` class
+
+Here's the reference information for the `Typer` class, with all its parameters, attributes and methods.
+
+You can import the `Typer` class directly from `typer`:
+
+```python
+from typer import Typer
+```
+
+::: typer.Typer
+    options:
+        members:
+            - callback
+            - command
+            - add_typer

mkdocs.yml

@@ -67,6 +67,25 @@ plugins:
   redirects:
     redirect_maps:
       typer-cli.md: tutorial/typer-command.md
+  mkdocstrings:
+    handlers:
+      python:
+        options:
+          extensions:
+            - griffe_typingdoc
+          show_root_heading: true
+          show_if_no_docstring: true
+          inherited_members: true
+          members_order: source
+          separate_signature: true
+          unwrap_annotated: true
+          filters:
+            - '!^_'
+          merge_init_into_class: true
+          docstring_section_style: spacy
+          signature_crossrefs: true
+          show_symbol_type_heading: true
+          show_symbol_type_toc: true
 
 nav:
   - Typer: index.md
@@ -138,6 +157,13 @@ nav:
       - tutorial/exceptions.md
       - tutorial/one-file-per-command.md
       - tutorial/typer-command.md
+  - Reference (Code API):
+    - reference/index.md
+    - reference/typer.md
+    - reference/run_launch.md
+    - reference/parameters.md
+    - reference/file_objects.md
+    - reference/context.md
   - Resources:
     - resources/index.md
     - help-typer.md

pyproject.toml

@@ -35,6 +35,7 @@ classifiers = [
 ]
 dependencies = [
     "click >= 8.0.0",
+    "annotated-doc >=0.0.2",
 ]
 readme = "README.md"