Fastapi: [QUESTION] Are there any api developer docs?

[joe-eklund]

First check

• [x] I used the GitHub search to find a similar issue and didn't find it.
• [x] I searched the FastAPI documentation, with the integrated search.
• [x] I already searched in Google "How to X in FastAPI" and didn't find any information.

Description

What I mean by api developer docs are basically something like sphinx docs for function definitions. This is usually generated from function docstrings (which I didn't see any in my small amount of browsing the FastAPI codebase). For example, here are the docs for github3 https://github3py.readthedocs.io/en/master/api-reference/index.html. It is an easy way to click through the entire package and see class and function definitions.

Does FastAPI have these? The tutorial docs look pretty good, but sometimes I just want to know what all the function parameters are independent of the context in a tutorial.

[tiangolo]

Not yet. I expect to use https://github.com/tomchristie/mkautodoc at some point.

But first I have to clean up some of the parameters, define a docstring style, and add docstrings everywhere.

[nsidnev]

@tiangolo
Hi! Just out of interest, but what do you think about using pawamoy/mkdocstrings? I recently used this project and it worked without any problems.

[joe-eklund]

I have used https://www.sphinx-doc.org/en/master/ before and they look pretty nice. Works very well for Python code in my opinion.

[dbanty]

@tiangolo if you were able to define a docstring style I'd be happy to start contributing some notes. I habitually check documentation in my IDE and would love to have some quick references available for FastAPI.

As far as picking a style, of course the mk tools want the docstrings to be in Markdown. Unfortunately PyCharm won't render / extract any useful information from the docstrings unless they are in one of it's supported formats (e.g. reStructuredText, Epytext) none of which use Markdown to my knowledge. Maybe that won't matter though because markdown is so easy to read unrendered.

[falkben]

I would also be happy to contribute once a style is finalized. I believe this is also missing in starlette...

[pawamoy]

@dbanty good point about PyCharm being able to handle docstrings or not. In my experience, it handles Google-style docstrings in Markdown pretty well. You can set it up in the Tools -> Python integrated tools -> Docstrings format -> Google. PyCharm will match parameters in the signature with the ones documented in the docstrings, warn you when some are missing from the docstring, or inversely, etc.

[dbanty]

@pawamoy yes it does! As you know I've recently started using your mkdocstrings for documenting a project. I've been using those Google-style docstrings and combining auto-generated API docs with manual docs which are inspired by (and therefore very similar to
) FastAPI's. Been working pretty well so far.

mkdocstrings definitely gets my endorsement for an option here.

[reillysiemens]

@tiangolo: My team and I have been evaluating FastAPI for use at our workplace, but the lack of API-level documentation for developers has caused a little friction for adoption. Is there something still blocking the decision to use mkautodoc, mkdocstrings, the classic Sphinx with reStructuredText, or some other option?

[Kludex]

At the point the issue was created mkdocstrings was just a POC, now it's more mature. I've seen people asking for it on gitter. What do you think @tiangolo ?