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

[tiangolo]

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

[tiangolo]

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

[pawamoy]

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]

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]

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]

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]

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]

@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]

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

[pawamoy]

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

[tiangolo]

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

[pawamoy]

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]

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]

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

[tiangolo]

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

[tiangolo]

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

[tiangolo]

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

[pawamoy]

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

[tiangolo]

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

[pawamoy]

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]

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