[NEED HELP] 📃 Update docs

[uriyyo]

Documentation should be updated.

Topics that should be covered:

• General information
• Customization
• Features
• Integrations
• Examples
• sqlachemy extension details

Missed features docs:

• Additional data
• Items transformers

Related issue:
#273
#269
#264

Library has bad documentation and I am not good at documentation writing. It will be great if somebody can help to improve documentation.

[JaeungJayJang]

Hello. Is this for the case where you want to do perform get request that returns list of data so you cut the data in certain size and return to the user? like.. the pagination in API request?

[letoss]

I was considering using this lib. Since it really lacks documentation, I can't make the decision. I'm not sure if it'd have a really big impact on my project.
I'm using APIRouter for registering my endpoints and I couldn't see any example using that, just FastAPI.

I think I'll wait until there is more documentation in place.

[HDM007]

Hey @uriyyo,
What topics are you hoping to broaden the docs on? I don't have a ton of time, but I take detailed notes when I work with new packages, so may be able to send some writing your way from time to time.

[uriyyo]

@HDM007 Thanks for your help. I hope to cover:

• items transformer
• additional data
• more customization examples
• sqlaclhemy extension docs with generated SQL examples

[HDM007]

Sure thing! I've already begun using the items transformer, so I can tackle that in my free time.

The way I understand it, the items transformer allows us to pass a function to format the paginated response;
e.g.

• if I retrieve a SQLAlchemy object from the db which doesn't immediately adapt to a Pydantic Schema, I can use paginate to apply complex PydanticSchemas to a collection
• if I want to retrieve price rates on an item and modify them per region, I could use a transformer to look at row, apply a rate multiplier to the price, and return a transformed item with updated prices based on the original rate.

I will go deeper into the package to understand more about the Transformer. Are there any critical details you'd like to point out/focus on?

[uriyyo]

I guess it will be enough just to add usage examples with minimal implementation details so users will know how to use this feature.

[leosok]

strangly this will work:
async def get_conversations_by_session(*, session: Session = Depends(get_session), session_id: str) -> Page[LogEntryResponseDTO]:

but the version in the version in the Readme.md

async def get_conversations_by_session(*, session: Session = Depends(get_session), session_id: str, response_model=Page[LogEntryResponseDTO]):

I could fix it by defining the response_type as above, but maybe someone should fix the docs here.

[uriyyo]

@leosok Both definitions are correct in terms of FastAPI.

This feature was added in FastAPI version 0.89.0 and README was written long-long time ago)

async def get_conversations_by_session(*, session: Session = Depends(get_session), session_id: str) -> Page[LogEntryResponseDTO]:
    ...

Thanks for pointing it, I will update README.md.

[widal001]

@uriyyo Really love this package, great work! I also (strangely) love writing technical documentation.

Personally, I've found the docs to be sufficient for my current usage of the tool, but would love to help fill in the gaps as needed. I saw that the three related issues you tagged in this were all closed.

Is there another section of the codebase you think could benefit from additional documentation?

[uriyyo]

@widal001 I would love it if you could help me with documentation.

I feel like there is a lot of functionality that is not covered in the documentation.

For instance, here is the functionality from https://github.com/uriyyo/fastapi-pagination/blob/main/fastapi_pagination/api.py that is not covered at all:

• resolve_params
• create_page
• set_params
• set_page
• set_items_transformer
• pagination_ctx

These are the first things that come to my mind, I am sure that there is more to cover. It will be also great to improve existing docs.

[widal001]

@uriyyo Thanks for flagging these items!

I'll take a closer look at that section of the code base, create the corresponding ticket(s), link them here for awareness, and aim to open up a PR in the next 1-2 weeks.

[Lord-V15]

I've been using the repo for my work involving PyMongo. I can help with some PyMongo examples similar to the code snippet shown for SQLAlchemy in the docs.

[uriyyo]

@Lord-V15 It will be really great, cause I'm not working with Mongo at all(

[uriyyo]

@widal001 @Lord-V15 Hi guys!

Are you still interested in docs improving?)

[Lord-V15]

@widal001 @Lord-V15 Hi guys!

Are you still interested in docs improving?)

Yes ! I will add some PyMongo examples for sure. Completely forgot about it my bad.
Should I follow the format of the SqlAlchemy example ?

[uriyyo]

Yup, please follow sqlachemy example. You can add as much info as you want. Thanks for your help 🙏

[widal001]

Hey @uriyyo I just created #1147 to track my work on the sections of the documentation you suggested

[djeni98]

I had problem testing if my queries were ok (using pytest). I was getting RuntimeError: Use params, add_pagination or pagination_ctx and had no clue about what should I do.

After a long time looking at the source code I discovered about set_params. It was literally in the error message, but I was not sure how to use params. In my case, I just added set_params in pytest.fixture.

It would be nice to have something about testing in the docs

[uriyyo]

Hi @djeni98,

Thanks for your feedback, I'm currently working on rewriting docs, so it should be better in future 🙏

[uriyyo]

I'm closing this issue as far as docs were fully rewritten, I would love to hear your feedback guys!