-
-
Notifications
You must be signed in to change notification settings - Fork 331
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: [WIP] Update routing/request/response docs #2912
Conversation
f8e1c1b
to
ddaefdf
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A great start! I know still a WIP but a couple of comments you can take or leave. Thanks!
Instances of :class:`~litestar.app.Litestar`, a special type of router that serves | ||
as the entry point of an application, in addition to receive the same configuration | ||
routers can |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Instances of :class:`~litestar.app.Litestar`, a special type of router that serves | |
as the entry point of an application, in addition to receive the same configuration | |
routers can | |
Instances of :class:`~litestar.app.Litestar`, the entry point of an application, and a | |
specialized type of router, so it can receive the same configuration as routers can |
This wording was a bit awkward - not sure if my suggestion is much better though!
Dynamic paths can be created with the help of path parameters. These are part of the | ||
path string and follow the basic form of ``{<parameter name>:<parameter type>}``, where | ||
``<parameter name>`` is the name of the parameter used to make its value available to | ||
the route handler and what will be represented in the OpenAPI schema, and | ||
``<parameter type>`` a basic Python type that this parameter will be validated against | ||
and, if possible, converted to. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These are part of the
path string and follow the basic form of{<parameter name>:<parameter type>}
, where
<parameter name>
is the name of the parameter used to make its value available to
the route handler and what will be represented in the OpenAPI schema, and
<parameter type>
a basic Python type that this parameter will be validated against
and, if possible, converted to.
This is quite a big sentence - might be better to break it up into smaller ideas, e.g., a sentence that introduces the two components of the parameter, then one explaining parameter name, and another to explain parameter type.
ddaefdf
to
6aa2ce4
Compare
This is an attempt to clean up the docs for routing, route handlers, parameters, requests and responses.
The individual chapters and sections currently lack clear boundaries and mix up a lot of topics, so that a user has to go through all of them to gather the necessary information.
The goal here is to split the sections not only functionality wise but also between usage and reference documentation, where the usage documentation should be more task focused (i.e. "how do I do X?"), while the reference should focus on the functionality of the components (i.e. "this class has these methods", "this decorator can be configured like so").
This is a work in progress. I am currently mainly trying to establish an outline for a sensible structure.