Documenting Applications¶
What is documenting?¶
Writing documentation (or "documenting", as view.py calls it) can be an important task when it comes to writing API's, but it can be extremely tedious to do manually. Other frameworks, such as FastAPI, have their own approaches to generating API documentation, a common method is by using OpenAPI.
OpenAPI is a good choice when it comes to this topic, but View does not support it. However, support is planned.
For now, View has it's own system internally that does not use OpenAPI. This means that client generation is not yet supported. If you would like to track this issue, see it here.
Writing Documentation¶
On a route, you may define a route's documentation in one of two ways:
- Passing
doc
to the router function (e.g.@get("/", doc="Homepage")
) - More versatile, adding a docstring to the route (e.g.
"""Homepage"""
)
Here's an example using both:
from view import new_app
app = new_app()
@app.get("/", doc="The homepage")
async def index():
...
@app.get("/hello")
async def hello():
"""A greeting to the user."""
app.docs("docs.md") # more on this function later
app.run()
Documenting Inputs¶
For route inputs, it's almost idential, except that you cannot use a docstring, and instead must use the doc
parameter. This syntax is the same across both query
and body
(including standard and direct).
from view import new_app
@app.get('/')
@app.query("greeting", str, doc="The greeting to be used by the server", default="hello")
async def index(greeting: str):
"""The homepage that returns a greeting to the user."""
return f"{greeting}, world!"
However, you may want to define documentation for certain object keys when using object types (i.e. they support __view_body__
or are handled internally). In this case, you can use typing.Annotated
and a docstring again
- The docstring defines a description for the overall class.
Annotated
can provide a description for a certain key.
from view import new_app
from typing import Annotated, NamedTuple
app = new_app()
class Person(NamedTuple):
"""A person in the world."""
first: Annotated[str, "Their first name."]
last: Annotated[str, "Their last name."]
@app.get("/")
@app.query("person", Person)
async def index(person: Person):
...
app.run()
Note: If you are on Python 3.8, you will get an error complaining about Annotated
not being a part of typing
. In this case, you can import Annotated
from typing_extensions
instead.
Autogeneration¶
View will generate your API documentation into a markdown document that you could render in something like MkDocs. This can be done via App.docs()
, which will generate the markdown and write it to a file for you.
There are, roughly speaking, two ways to write to a file via App.docs()
:
- Passing it a
str
orPath
. - Passing it a
TextIO[str]
file wrapper.
from view import new_app
from pathlib import Path
app = new_app()
app.docs("docs.md")
app.docs(Path("docs.md"))
with open("docs.md", "w") as f:
app.docs(f)
view.app.App.docs(file: str | TextIO | Path | None = None, *, encoding: str = 'utf-8', overwrite: bool = True) -> str | None
¶
Generate documentation for the app.
Source code in src/view/app.py
Review¶
"Documenting" in terms of View, is the act of writing documentation. Other frameworks use OpenAPI as a versatile solution to doing this, but view.py does not yet support this.
To write a description for a route, you may pass a doc
parameter to the router call, or instead add a docstring to the route function itself. In a route input, it's quite similar, where you pass doc
to the input function, but using a docstring is not allowed. However, this rule is broken in the case of using an object as the type. When using an object, you must provide a docstring to define the class's description, and use typing.Annotated
(or typing_extensions.Annotated
) to set descriptions for object attributes.
Finally, you can actually generate the markdown content via the docs()
method on your App
. docs()
can take three types of parameters:
- A
str
, in which it opens the file path and attempts to write to it. - A
Path
, in which the same thing happens. - A
TextIO[str]
(file wrapper), where the file is not opened by View, and is instead just written to via the wrapper.