Skip to content
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

Closed
wants to merge 1 commit into from

Conversation

provinzkraut
Copy link
Member

@provinzkraut provinzkraut commented Dec 16, 2023

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.

Copy link
Contributor

@peterschutt peterschutt left a 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!

Comment on lines +19 to +21
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
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
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!

Comment on lines +157 to +162
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.
Copy link
Contributor

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.

Signed-off-by: Janek Nouvertné <25355197+provinzkraut@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants