Thanks to visit codestin.com
Credit goes to github.com

Skip to content

✨ Add reference (code API) docs with PEP 727, add subclass with custom docstrings for BackgroundTasks, refactor docs structure#10392

Merged
tiangolo merged 50 commits into
masterfrom
ref-docs
Oct 18, 2023
Merged

✨ Add reference (code API) docs with PEP 727, add subclass with custom docstrings for BackgroundTasks, refactor docs structure#10392
tiangolo merged 50 commits into
masterfrom
ref-docs

Conversation

@tiangolo

@tiangolo tiangolo commented Oct 5, 2023 •
edited
Loading

Copy link
Copy Markdown
Member

✨ Add reference (code API) docs with PEP 727, add subclass with custom docstrings for BackgroundTasks, refactor docs structure.

@tiangolo tiangolo mentioned this pull request Oct 5, 2023
Open
25 tasks
@tiangolo

tiangolo commented Oct 5, 2023

Copy link
Copy Markdown
Member Author

📝 Docs preview for commit df4c501 at: https://5419df85.fastapitiangolo.pages.dev

@Kludex Kludex mentioned this pull request Oct 6, 2023
Closed
@pawamoy

pawamoy commented Oct 6, 2023

Copy link
Copy Markdown
Contributor

If you install Black alongside mkdocstrings-python, it will use it to format long signatures (such as fastapi.FastAPI).
Also, tables are a bit too large and have an horizontal scrollbar, maybe the list or spacy formats for docstring sections would be more readable? Happy to work with you on improving rendering 🙂

@tiangolo

tiangolo commented Oct 12, 2023

Copy link
Copy Markdown
Member Author

Thanks @pawamoy!

Is there a way to render the types using the latest syntax, even if the source uses older syntax?

For example, the code for some parameters is Optional[str], to be compatible with Python 3.8, etc. But I would like that to show up in the docs as str | None.

It would probably be something like running pyupgrade on the type before it is rendered or something like that... but not sure if it's possible (or maybe there's already a config for that I haven't found).

@pawamoy

pawamoy commented Oct 12, 2023 •
edited
Loading

Copy link
Copy Markdown
Contributor

There's no such option, but I'll see how we can make it happen. Also I suppose you cannot use from __future__ import annotations (and then use PEP 604's | syntax) for Pydantic/runtime reasons?

@tiangolo

tiangolo commented Oct 12, 2023

Copy link
Copy Markdown
Member Author

Thanks @pawamoy!

Also I suppose you cannot use from __future__ import annotations (and then use PEP 604's | syntax) for Pydantic/runtime reasons?

I'm not fully sure, I might be able to do that, at least in some places. It's funny and ironic that I would recommend people not to use from __future__ import annotations to not break/complicate their FastAPI and Pydantic apps... but I might actually be able to use it at least in some places (Pydantic already does that as well). 😅 I will try that as well.

@pawamoy

pawamoy commented Oct 12, 2023

Copy link
Copy Markdown
Contributor

As long as you know what you're doing 😉 And it's only for 1 year and 11 months, until 3.9 is EOL 🤫

tiangolo
tiangolo commented Oct 13, 2023
View reviewed changes
Comment thread fastapi/applications.py Outdated
Comment on lines +644 to +646
"""
---
"""

@tiangolo tiangolo Oct 13, 2023

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pawamoy I'm noticing that to render the __init__() parameters I need to have some non-empty docstring in the __init__() method, even if there's already a class docstring...

Am I doing something wrong in the configs or is it expected?

@pawamoy pawamoy Oct 13, 2023 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I noticed that in the PR yes. That's probably an oversight (in the PEP 727 extension), I'll take a look :)

@pawamoy pawamoy Oct 16, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is now fixed by latest versions of Griffe and griffe-typingdoc 😄

@tiangolo tiangolo Oct 17, 2023

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you! ...although I can't seem to make it work yet 🤔

@pawamoy pawamoy Oct 17, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you tell me what is not working? I tried locally to remove the docstring from fastapi.FastAPI.__init__ and the parameters are correctly inserted into the class docs.

tiangolo added 16 commits October 15, 2023 13:12
@tiangolo
📝 Add docstrings for OpenAPI docs utils
92573b3
@tiangolo
📝 Add docstrings for security utils
0cae830
@tiangolo
📝 Add docstrings for UploadFile
9830055
@tiangolo
📝 Update docstrings in FastAPI class
d5518fb
@tiangolo
📝 Add docstrings for path operation methods
da98d29
@tiangolo
📝 Add docstring for jsonable_encoder
3e2a049
@tiangolo
📝 Add docstrings for exceptions
8a672af
@tiangolo
📝 Add docstsrings for parameter functions
9341871
@tiangolo
📝 Add docstrings for responses
f77ee85
@tiangolo
📝 Add docstrings for APIRouter
a03b4c3
@tiangolo
♻️ Sub-class BackgroundTasks to document it with docstrings
e06f01f
@tiangolo
📝 Update usage of background tasks in dependencies
222f6ac
@tiangolo
✅ Update tests with new deprecation warnings
496cf7d
@tiangolo
📝 Add new reference docs
6882e9c
@tiangolo
🔧 Update MkDocs with new reference docs
8d224ed
@tiangolo
✅ Update pytest fixture, deprecation is raised only once
f55ce13
@tiangolo

tiangolo commented Oct 18, 2023

Copy link
Copy Markdown
Member Author

Awesome, thanks @pawamoy! 🚀

For some reason, I hadn't found the insiders installation, and now I see that it's quite open there... I was probably too tired and didn't see it 😅 🙈

@tiangolo

tiangolo commented Oct 18, 2023

Copy link
Copy Markdown
Member Author

📝 Docs preview for commit e2c3672 at: https://690c34e1.fastapitiangolo.pages.dev

@tiangolo

tiangolo commented Oct 18, 2023

Copy link
Copy Markdown
Member Author

📝 Docs preview for commit c34b8c9 at: https://eca9a21b.fastapitiangolo.pages.dev

@tiangolo tiangolo changed the title ✨ Add reference (code API) docs ✨ Add reference (code API) docs, add subclass with custom docstrings for BackgroundTasks, refactor docs structure Oct 18, 2023
@tiangolo

tiangolo commented Oct 18, 2023

Copy link
Copy Markdown
Member Author

📝 Docs preview for commit 77cb0c7 at: https://ecb1abc9.fastapitiangolo.pages.dev

@tiangolo tiangolo changed the title ✨ Add reference (code API) docs, add subclass with custom docstrings for BackgroundTasks, refactor docs structure ✨ Add reference (code API) docs with PEP 727, add subclass with custom docstrings for BackgroundTasks, refactor docs structure Oct 18, 2023
@tiangolo

tiangolo commented Oct 18, 2023

Copy link
Copy Markdown
Member Author

📝 Docs preview for commit ac82b9e at: https://2124dde5.fastapitiangolo.pages.dev

@pawamoy

pawamoy commented Oct 18, 2023

Copy link
Copy Markdown
Contributor

I'll tell you when griffe-typing-deprecated is up-to-date with latest Griffe so you can list it in mkdocs.yml 🙂

@tiangolo

tiangolo commented Oct 18, 2023

Copy link
Copy Markdown
Member Author

Thanks @pawamoy! For now, I'll merge and release this. 😎 🚀

@tiangolo tiangolo merged commit 05ca41c into master Oct 18, 2023
@tiangolo tiangolo deleted the ref-docs branch October 18, 2023 12:36
@pawamoy

pawamoy commented Oct 18, 2023 •
edited
Loading

Copy link
Copy Markdown
Contributor

Congrats! I'm amazed by your efficiency here: in just a few days you managed to document the (almost?) entire API 🤯 Also it's super exciting to see a decently-sized code base use PEP 727 docs 😄 It's looking great!

@pawamoy

pawamoy commented Oct 18, 2023

Copy link
Copy Markdown
Contributor

Oh and for signature_crossrefs to take effect, you need to enable show_signature_annotations too!

nilslindemann pushed a commit to nilslindemann/fastapi that referenced this pull request Oct 18, 2023
Sync with fastapi#10392
4ca241d
nilslindemann pushed a commit to nilslindemann/fastapi that referenced this pull request Oct 18, 2023
Sync with fastapi#10392
0974a4e
nilslindemann pushed a commit to nilslindemann/fastapi that referenced this pull request Oct 18, 2023
Sync with fastapi#10392
fff815f
nilslindemann pushed a commit to nilslindemann/fastapi that referenced this pull request Oct 18, 2023
Sync with fastapi#10392
01783f7
@pawamoy pawamoy mentioned this pull request Nov 9, 2023
Closed
nilslindemann pushed a commit to nilslindemann/fastapi that referenced this pull request Jan 17, 2024
Hide navigation
37bc57d 
These were added to the Englisch docs in fastapi#10392.

I went through all instances of:

* docs/index.md
* docs/features.md
* docs/fastapi-people.md

in the rest of the docs and added this where missing. The PRs for the German translations (fastapi#10283, fastapi#10284, fastapi#10285) already contain this change.
@Gourab-Himel Gourab-Himel mentioned this pull request Jul 1, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer
@pawamoy pawamoy pawamoy left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@tiangolo @pawamoy