-
-
Notifications
You must be signed in to change notification settings - Fork 1.5k
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
Improvements to Pagination Documentation: Type Information, Argument Descriptions, and Redundant Sections #9442
Comments
Hi @ManorSailor, thanks for this detailed issue! I'm not an Astro maintainer but I helped to improve the type information on the API reference page. I'd like to clarify some points regarding this page.
Edit: I answered a bit quickly, I didn't remember that the This remark about the first point is a bit outdated (see above: Edit:), but I leave it there if it can help with the reflection >
export interface Page<T = any> {
/** result */
data: T[];
/** metadata */
/** the count of the first item on the page, starting from 0 */
start: number;
/** the count of the last item on the page, starting from 0 */
end: number;
/** total number of results */
total: number;
/** the current page number, starting from 1 */
currentPage: number;
/** number of items per page (default: 10) */
size: number;
/** number of last page */
lastPage: number;
url: {
/** url of the current page */
current: string;
/** url of the previous page (if there is one) */
prev: string | undefined;
/** url of the next page (if there is one) */
next: string | undefined;
/** url of the first page (if the current page is not the first page) */
first: string | undefined;
/** url of the next page (if the current page in not the last page) */
last: string | undefined;
};
} This is a very long type... and writing every properties in That said, perhaps we can improve the description below to help better understand what it is about. Here is a suggestion based on the existing description:
What do you think? Would it have been clearer for you at the time of implementation?
To be more precise, the type would be However, not all users are familiar with Typescript. So we thought that Here are the two propositions that come to mind as I write.
I agree, there is a problem here! This should be fixed. I think in this case
Ah I think I understand now. You're using Typescript and it infers the type to be There is
The Maybe a "tip" under
Yes for such complicated types, we preferred not to put anything... It's not easy to simplify without losing information... and again, you have to think about those who are used to Typescript and those who are not. 😅
You are right, there is a problem with the wording. The properties listed are not arguments but options. paginate(data, options) Where, {
pageSize: 10,
params: { /* some additional params */ },
props: { /* some additional props */ },
}
On this point I rather agree... but there are drawbacks (that's why I didn't insist in the issue you quote, I understand Sarah's reluctance). The main problem is that if we move this block to the API reference page, we would have to do the same thing with all the properties listed on this page. It doesn't make sense to do it for one but not the other but it could make reading more complicated for users. So I'm not sure it's the best thing to do... However, since we detail the properties in the reference I am still not sure that this block is an added value... I tend to agree that the link is enough. Regarding links to the source code, I am hesitant... The less experienced might be scared to find themselves in the source code while an idea of the expected types might be useful to them. Providing the information directly in the documentation seems a good compromise. Even if it adds maintenance... Again, thanks for this detailed issue! 👍🏽 I agree that there are some improvements/fixes to be made. Feel free to react to my remarks! |
Hey @ArmandPhilippot, thanks again for your input! I really appreciate the thorough response. I mostly agree with your suggestions, but I’d like to revisit a few points.
I’ve spent too much time working with Python’s type annotations and ended up mixing it with TypeScript. Thanks for the correction! Whatever is ultimately decided for Regarding the remaining points, I don’t have anything else to add.
When you refer to this page, I assume you’re talking about the Routing page? If so, I didn’t notice any other sections on that page containing full API references. For example, the rewrite section links back to its own API reference, but that’s for a standalone method, not an object like I don’t have anything else to add at this point. Let’s wait for input from the maintainers. That’s all for now! Thanks again for your reply. While reading it, I really appreciated how thoughtful your suggestions are. They’re clearly aligned with what the average user would expect. |
Why not, I don't have a strong opinion on this. The reason I suggested And maybe we should update all mentions of
Ah indeed, I hadn't thought about data retrieved from an API directly! I was thinking "collections" after rereading the description below (creates one URL for every page of the paginated collection)... I didn't go as far as the example. In this case, As for Afterwards, maybe I'm overthinking... In Generally, we try to keep the type indicated in the sources. When it involves Typescript generics, we try to simplify or modify slightly to make it easier to read. If it is too complicated, we omit the
Oh no, sorry for the confusion. I was referring to So what I was suggesting was to just delete that block since we have a link to To resume:1. We agree to add a 2. The If we mention the generic for Also, since Array of data returned from the `paginate()` function for the current page. 3. A hint should be added to explain how to type the array returned by If my suggestion works with @ManorSailor issue, we could add an aside with a link to :::tip
When using Typescript, you will need the `GetStaticPaths` type helper to access your data with type safety. You can see how to use it in the [Typescript reference](https://docs.astro.build/en/guides/typescript/#infer-getstaticpaths-types).
::: I'd say we could put this "tip" in the 4. Missing signature information for the paginate function I think we agree that the type is too complex to be useful in documentation. 5. Missing argument from the paginate list If I am not mistaken, a reformulation is sufficient here: paginate() has the following options:
- pageSize - The number of items shown per page (10 by default)
- params - Send additional parameters for creating dynamic routes
- props - Send additional props to be available on each page 6. Routing: the It seems that we share the same opinion on this point: this section seems redundant with the API reference and the link seems enough. Maybe we should remove it? (see also #8929) 7. (added by myself) Make If we have to edit Furthermore, when using
Maybe we should only use one? So either @ManorSailor Feel free to check that I haven't forgotten anything in the summary and that you agree with what I wrote. If we agree on these points, I have nothing else to add from my side while waiting for further feedback! |
Well, this has been an amazing discussion! I appreciate everyone's thoroughness and care here, and @ManorSailor I extra appreciate your realizing that this is potentially a big can of worms that needed some discussion before just making "issueless PR". And indeed, this has led to some real thought here to figure out exactly what is needed. I am hereby approving a PR! I think it's clear that you both have a fantastic sense of what is necessary, and helpful (and what is not, which is also a consideration for docs so that people aren't overwhelmed and are steered towards a happy path of success). I am confident that after this discussion, whatever you come up with will be valuable, and I think it's time to move this into a PR so that we can actually see it in action and haggle over details there! Are you up for creating a PR, @ManorSailor ? |
@sarah11918 I'd be more than happy to create a PR! I'll drop a PR by tomorrow evening. |
📚 Subject area/topic
Pagination - API Reference
📋 Page(s) affected (or suggested, for new content)
https://docs.astro.build/en/reference/api-reference/#the-pagination-page-prop
https://docs.astro.build/en/reference/api-reference/#paginate
(Potentially) https://docs.astro.build/en/guides/routing/#complete-api-reference
📋 Description of content that is out-of-date or incorrect
A couple of days ago, I was implementing pagination in an Astro-based project on GitHub. While working on it, I faced a few challenges related to the documentation on pagination. I was able to resolve them by exploring the documentation, the Astro codebase, or a combination of both. After addressing the issues, I realized that these changes could be reflected in the documentation to prevent similar challenges for future users. Initially, I planned to create a PR right away, but the scope of this task felt slightly beyond the realm of "issue-less PRs." Therefore, I’ve created this issue first for approval.
On API Reference:
Under #Page Props:
Page
propPage
is ageneric
type.Type
attribute under the title like:Type: Page<T = any>
page.data
property simply mentionsArray
. To be more precise, this could be updated toArray[T]
following the changes mentioned above.page.data
prop as a function in its description. Perhaps, the intent was to mention eitherpaginate
orgetStaticPaths
function?page.data
when using Content Collections. It may have been my oversight, but it was not immediately obvious that I had to useCollectionEntry
utility type. This could be worth mentioning in the reference page... or perhaps in the Pagination section underRouting
guide.Under #paginate:
paginate
functionpaginate
list:The reference mentions the
data
argument before the example, but it is missing from the list above. If the goal is to highlight optional arguments, then the wording could be improved.On Routing guide, under Pagination#Complete API Reference:
This section seems redundant. Issue #8929 addressed the same concern, and the conclusion was to keep it due to the lack of a better solution. However, reading through the comments, it seems the pagination section previously didn't link back to the API reference page—perhaps the main reason for keeping it. Here are a few reasons why I think removing this section entirely might be beneficial:
As @sarah11918 suggested, we could move this type block into the reference page, as it does provide a useful high-level overview of the Page API. However, another argument can be made that it might be better to link to the actual type in the Astro codebase to avoid further maintenance costs.
🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)
No response
The text was updated successfully, but these errors were encountered: