Commit Graph

24 Commits

Author SHA1 Message Date
Sebastián Ramírez 05ca41cfd1
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
2023-10-18 16:36:40 +04:00
Sebastián Ramírez 0a8423d792
🔨 Enable linenums in MkDocs Material during local live development to simplify highlighting code (#9769) 2023-06-30 18:23:02 +02:00
Sebastián Ramírez ed297bb2e0
Add Material for MkDocs Insiders features and cards (#9748)
*  Add dependencies for MkDocs Insiders

* 🙈 Add Insider's .cache to .gitignore

* 🔧 Update MkDocs configs for Insiders

* 💄 Add custom Insiders card layout, while the custom logo is provided from upstream

* 🔨 Update docs.py script to dynamically enable insiders if it's installed

* 👷 Add cache for MkDocs Material Insiders' cards

* 🔊 Add a small log to the docs CLI

* 🔊 Tweak logs, only after exporting languages

* 🐛 Fix accessing non existing env var

* 🔧 Invalidate deps cache

* 🔧 Tweak cache IDs

* 👷 Update cache for installing insiders

* 🔊 Log insiders

* 💚 Invalidate cache

* 👷 Tweak cache keys

* 👷 Trigger CI and test cache

* 🔥 Remove cache comment

* ️ Optimize cache usage for first runs of docs

* 👷 Tweak cache for MkDocs Material cards

* 💚 Trigger CI to test cache
2023-06-26 16:05:43 +02:00
Sebastián Ramírez 5656ed09ef
Refactor docs for building scripts, use MkDocs hooks, simplify (remove) configs for languages (#9742)
*  Add MkDocs hooks to re-use all config from en, and auto-generate missing docs files form en

* 🔧 Update MkDocs config for es

* 🔧 Simplify configs for all languages

*  Compute available languages from MkDocs Material for config overrides in hooks

* 🔧 Update config for MkDocs for en, to make paths compatible for other languages

* ♻️ Refactor scripts/docs.py to remove all custom logic that is now handled by the MkDocs hooks

* 🔧 Remove ta language as it's incomplete (no translations and causing errors)

* 🔥 Remove ta lang, no translations available

* 🔥 Remove dummy overrides directories, no longer needed

*  Use the same missing-translation.md file contents for hooks

* ️ Restore and refactor new-lang command

* 📝 Update docs for contributing with new simplified workflow for translations

* 🔊 Enable logs so that MkDocs can show its standard output on the docs.py script
2023-06-25 14:33:58 +02:00
Sebastián Ramírez c09e5cdfa7
👷 Refactor Docs CI, run in multiple workers with a dynamic matrix to optimize speed (#9732) 2023-06-24 02:00:12 +02:00
Sebastián Ramírez 884203676d
👷 Tweak build-docs to improve CI performance (#5699) 2022-11-27 14:22:30 +00:00
Sebastián Ramírez fa74093440
Use Ruff for linting (#5630) 2022-11-13 19:19:04 +01:00
Sebastián Ramírez e866a2c7e1
🐛 Fix calling `mkdocs` for languages as a subprocess to fix/enable MkDocs Material search plugin (#5501)
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
2022-10-16 17:01:38 +02:00
Sebastián Ramírez 273b2cd646
🐛 Fix docs script to generate a new translation language with overrides boilerplate (#3202) 2021-05-10 09:15:39 +02:00
Sebastián Ramírez da86791224
Add new Deta banner badge with new sponsorship tier 🙇 (#3194) 2021-05-08 19:50:56 +02:00
Sebastián Ramírez 9f89399f5e
🌐 Add docs lang selector widget (#2542)
*  Add language selector widget

* 🔧 Update script to re-generate MkDocs configs, including langs widget

* 🔧 Update languages MkDocs configs, with lang selector widget
2020-12-19 20:54:02 +01:00
Sebastián Ramírez 6e9b771abf
🐛 Fix docs overrides directory for translations (#2541)
* 🙈 Add .gitignore files to keep overrides directories for translations to fix serving live locally during translations

* ♻️ Refactor docs scripts to handle language overrides (newsletter notification)
2020-12-19 19:54:54 +01:00
Sebastián Ramírez e6f8aa8756
Add newsletter: FastAPI and friends (#2509)
*  Add newsletter: FastAPI and friends

* 🔧 Update MkDocs config for announcement

* 🔧 Update generation script to include overrides for announcements
2020-12-13 16:33:46 +01:00
Sebastián Ramírez a42c690496
📝 Add deployment to Deta, the first gold sponsor 🎉 (#2303)
* 📝 Add docs for sponsors

* 📝 Add docs for deploying on Deta

* 🍱 Add Deta docs screenshots

* ♻️ Refactor and separate deployment docs

* 📝 Update internal docs links to Deployment

* 📝 Update links in Deta tutorial

* 🍱 Update sponsors images

* 🔧 Use sponsors data from YAML

* 📝 Update sponsors in languages docs

*  Update docs generation scripts

*  Update README.md testing

* 📝 Update main README

* 🔧 Update fastapi-people action handling individual sponsors

* ✏️ Fix typos in Deta tutorial
2020-11-05 21:50:37 +01:00
Sebastián Ramírez f88ffd1a0b
️ Build docs for languages in parallel in subprocesses to speed up CI (#2242) 2020-10-25 12:59:13 +01:00
Sebastián Ramírez 8650dee4bc
🐛 Fix docs order generation for partial translations (#2238) 2020-10-24 13:32:59 +02:00
Sebastián Ramírez a5c03ba1b7
External links in docs with data file (#1701)
*  Add mkdocs-markdownextradata-plugin for docs

* 🔧 Update MkDocs config file(s) to include external data

*  Add external links data file

* 📝 Use external data file in External Links

* ♻️ Update data files for langs

The cost is some duplication 😔, these files are updated by the script, but to be able to serve locally they have to be duplicated

*  Update docs script to copy data files

* 🔥 Remove needed duplication of data files for live docs in translations
2020-07-10 14:31:44 +02:00
Sebastián Ramírez e4f0947821
Allow Unicode in MkDocs for translations instead of escaped chars (#1419) 2020-05-16 15:17:24 +02:00
Sebastián Ramírez 483bce3ae1
⬆️ Upgrade to MkDocs Material 5 and update docs scripts (#1225)
* ⬆️ Upgrade mkdocs.yml configs for MkDocs Material 5

*  Update docs.py to always update mkdocs.yml

* 🌐 Update mkdocs.yml for translations

* 🔧 Update MkDocs config

*  Add tabs for alternative options

* ⬆️ Update termynal setup with new CSS classes

* 🔧 Sync / Update mkdocs.yml for languages
2020-04-08 06:25:01 +02:00
Sebastián Ramírez 06eaa32bf0
🔧 Update docs script to make sure languages are always sorted (#1189) 2020-03-30 20:41:50 +02:00
Sebastián Ramírez 459f0e11e5
🏁 Update Windows development environment and tests (#1179)
* 🏁 Fix ./scripts/docs.py encoding for Windows

* 🔥 Remove ujson from tests as it prevents Windows development

It's still tested by Starlette anyway

* 📝 Update development instructions for Windows

* 🎨 Update format for WSGIMiddleware example

*  Update tests to run on Windows
2020-03-29 17:04:04 +02:00
Sebastián Ramírez 7625e1e386
📝 Update and simplify translations docs (#1171) 2020-03-27 10:20:39 +01:00
Camila Gutierrez c13b54ad0e
🏁 Change docs address to localhost for Windows (#1169) 2020-03-26 22:22:34 +01:00
Sebastián Ramírez 6205935323
Add support for docs translations (#1168)
* 🌐 Refactor file structure to support internationalization

*  Update tests changed after i18n

* 🔀 Merge Typer style from master

* 🔧 Update MkConfig with Typer-styles

* 🎨 Format mkdocs.yml with cannonical form

* 🎨 Format mkdocs.yml

* 🔧 Update MkDocs config

*  Add docs translation scripts dependencies

*  Add Typer scripts to handle translations

*  Add missing translation snippet to include

*  Update contributing docs, add docs for translations

* 🙈 Add docs_build to gitignore

* 🔧 Update scripts with new locations and docs scripts

* 👷 Update docs deploy action with translations

* 📝 Add note about languages not supported in the theme

*  Add first translation, for Spanish
2020-03-26 20:09:53 +01:00