Skip to content

Commit 05ca41c

Browse files
tiangolotiangolo
authored
✨ Add reference (code API) docs with PEP 727, add subclass with custom docstrings for BackgroundTasks, refactor docs structure (#10392)
* ➕ Add mkdocstrings and griffe-typingdoc to dependencies * 🔧 Add mkdocstrings configs to MkDocs * 📝 Add first WIP reference page * ⬆️ Upgrade typing-extensions to the minimum version including Doc() * 📝 Add docs to FastAPI parameters * 📝 Add docstrings for OpenAPI docs utils * 📝 Add docstrings for security utils * 📝 Add docstrings for UploadFile * 📝 Update docstrings in FastAPI class * 📝 Add docstrings for path operation methods * 📝 Add docstring for jsonable_encoder * 📝 Add docstrings for exceptions * 📝 Add docstsrings for parameter functions * 📝 Add docstrings for responses * 📝 Add docstrings for APIRouter * ♻️ Sub-class BackgroundTasks to document it with docstrings * 📝 Update usage of background tasks in dependencies * ✅ Update tests with new deprecation warnings * 📝 Add new reference docs * 🔧 Update MkDocs with new reference docs * ✅ Update pytest fixture, deprecation is raised only once * 🎨 Update format for types in exceptions.py * ♻️ Update annotations in BackgroundTask, `Annotated` can't take ParamSpec's P.args or P.kwargs * ✏️ Fix typos caught by @pawamoy * 🔧 Update and fix MkDocstrings configs from @pawamoy tips * 📝 Update reference docs * ✏️ Fix typos found by @pawamoy * ➕ Add HTTPX as a dependency for docs, for the TestClient * 🔧 Update MkDocs config, rename websockets reference * 🔇 Add type-ignores for Doc as the stubs haven't been released for mypy * 🔥 Remove duplicated deprecated notice * 🔇 Remove typing error for unreleased stub in openapi/docs.py * ✅ Add tests for UploadFile for coverage * ⬆️ Upgrade griffe-typingdoc==0.2.2 * 📝 Refactor docs structure * 🔨 Update README generation with new index frontmatter and style * 🔨 Update generation of languages, remove from top menu, keep in lang menu * 📝 Add OpenAPI Pydantic models * 🔨 Update docs script to not translate Reference and Release Notes * 🔧 Add reference for OpenAPI models * 🔧 Update MkDocs config for mkdocstrings insiders * 👷 Install mkdocstring insiders in CI for docs * 🐛 Fix MkDocstrings insiders install URL * ➕ Move dependencies shared by docs and tests to its own requirements file * 👷 Update cache keys for test and docs dependencies * 📝 Remove no longer needed __init__ placeholder docstrings * 📝 Move docstring for APIRouter to the class level (not __init__ level) * 🔥 Remove no longer needed dummy placeholder __init__ docstring
1 parent 3fa44aa commit 05ca41c

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

60 files changed

+11811
-1008
lines changed

‎.github/workflows/build-docs.yml‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,14 +44,17 @@ jobs:
4444
id: cache
4545
with:
4646
path: ${{ env.pythonLocation }}
47-
key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt') }}-v06
47+
key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt', 'requirements-docs-tests.txt') }}-v06
4848
- name: Install docs extras
4949
if: steps.cache.outputs.cache-hit != 'true'
5050
run: pip install -r requirements-docs.txt
5151
# Install MkDocs Material Insiders here just to put it in the cache for the rest of the steps
5252
- name: Install Material for MkDocs Insiders
5353
if: ( github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false ) && steps.cache.outputs.cache-hit != 'true'
54-
run: pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
54+
run: |
55+
pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
56+
pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/griffe-typing-deprecated.git
57+
pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/mkdocstrings-python.git
5558
- name: Export Language Codes
5659
id: show-langs
5760
run: |
@@ -80,13 +83,16 @@ jobs:
8083
id: cache
8184
with:
8285
path: ${{ env.pythonLocation }}
83-
key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt') }}-v06
86+
key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt', 'requirements-docs-tests.txt') }}-v06
8487
- name: Install docs extras
8588
if: steps.cache.outputs.cache-hit != 'true'
8689
run: pip install -r requirements-docs.txt
8790
- name: Install Material for MkDocs Insiders
8891
if: ( github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false ) && steps.cache.outputs.cache-hit != 'true'
89-
run: pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
92+
run: |
93+
pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
94+
pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/griffe-typing-deprecated.git
95+
pip install git+https://${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/mkdocstrings-python.git
9096
- name: Update Languages
9197
run: python ./scripts/docs.py update-languages
9298
- uses: actions/cache@v3

‎.github/workflows/test.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ jobs:
2929
id: cache
3030
with:
3131
path: ${{ env.pythonLocation }}
32-
key: ${{ runner.os }}-python-${{ env.pythonLocation }}-pydantic-v2-${{ hashFiles('pyproject.toml', 'requirements-tests.txt') }}-test-v06
32+
key: ${{ runner.os }}-python-${{ env.pythonLocation }}-pydantic-v2-${{ hashFiles('pyproject.toml', 'requirements-tests.txt', 'requirements-docs-tests.txt') }}-test-v06
3333
- name: Install Dependencies
3434
if: steps.cache.outputs.cache-hit != 'true'
3535
run: pip install -r requirements-tests.txt
@@ -62,7 +62,7 @@ jobs:
6262
id: cache
6363
with:
6464
path: ${{ env.pythonLocation }}
65-
key: ${{ runner.os }}-python-${{ env.pythonLocation }}-${{ matrix.pydantic-version }}-${{ hashFiles('pyproject.toml', 'requirements-tests.txt') }}-test-v06
65+
key: ${{ runner.os }}-python-${{ env.pythonLocation }}-${{ matrix.pydantic-version }}-${{ hashFiles('pyproject.toml', 'requirements-tests.txt', 'requirements-docs-tests.txt') }}-test-v06
6666
- name: Install Dependencies
6767
if: steps.cache.outputs.cache-hit != 'true'
6868
run: pip install -r requirements-tests.txt

‎docs/en/docs/about/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# About
2+
3+
About FastAPI, its design, inspiration and more. 🤓

‎docs/en/docs/fastapi-people.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
hide:
3+
- navigation
4+
---
5+
16
# FastAPI People
27

38
FastAPI has an amazing community that welcomes people from all backgrounds.

‎docs/en/docs/features.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
hide:
3+
- navigation
4+
---
5+
16
# Features
27

38
## FastAPI features

‎docs/en/docs/help/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Help
2+
3+
Help and get help, contribute, get involved. 🤝

‎docs/en/docs/index.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,12 @@
1+
---
2+
hide:
3+
- navigation
4+
---
5+
6+
<style>
7+
.md-content .md-typeset h1 { display: none; }
8+
</style>
9+
110
<p align="center">
211
<a href="https://fastapi.tiangolo.com"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" alt="FastAPI"></a>
312
</p>

‎docs/en/docs/learn/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Learn
2+
3+
Here are the introductory sections and the tutorials to learn **FastAPI**.
4+
5+
You could consider this a **book**, a **course**, the **official** and recommended way to learn FastAPI. 😎

‎docs/en/docs/reference/apirouter.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# `APIRouter` class
2+
3+
Here's the reference information for the `APIRouter` class, with all its parameters,
4+
attributes and methods.
5+
6+
You can import the `APIRouter` class directly from `fastapi`:
7+
8+
```python
9+
from fastapi import APIRouter
10+
```
11+
12+
::: fastapi.APIRouter
13+
options:
14+
members:
15+
- websocket
16+
- include_router
17+
- get
18+
- put
19+
- post
20+
- delete
21+
- options
22+
- head
23+
- patch
24+
- trace
25+
- on_event

‎docs/en/docs/reference/background.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Background Tasks - `BackgroundTasks`
2+
3+
You can declare a parameter in a *path operation function* or dependency function
4+
with the type `BackgroundTasks`, and then you can use it to schedule the execution
5+
of background tasks after the response is sent.
6+
7+
You can import it directly from `fastapi`:
8+
9+
```python
10+
from fastapi import BackgroundTasks
11+
```
12+
13+
::: fastapi.BackgroundTasks

0 commit comments

Comments
 (0)