Add documentation

[anand2312]

This PR sets up documentation for the project using sphinx and furo, and adds a lot of missing type-hints/docstrings.
The documentation is by no means complete with this, but I think it's a start 😄

To view the documentation, checkout this branch and run make html in the docs directory.

This PR also adds some code changes:

• Reset session.params / headers in the execute method, instead of creating a new httpx.Client for every request

(I forgot to make that a separate PR, sorry 😅 )

[codecov]

Codecov Report

Merging #111 (6607674) into master (53f7d18) will increase coverage by 1.58%.
The diff coverage is 90.80%.

@@            Coverage Diff             @@
##           master     #111      +/-   ##
==========================================
+ Coverage   90.66%   92.25%   +1.58%     
==========================================
  Files          22       22              
  Lines         911      930      +19     
==========================================
+ Hits          826      858      +32     
+ Misses         85       72      -13     

Impacted Files	Coverage Δ
postgrest_py/_sync/request_builder.py	92.85% <75.00%> (+3.96%)	⬆️
postgrest_py/_async/client.py	89.65% <80.00%> (+16.12%)	⬆️
postgrest_py/_async/request_builder.py	92.85% <80.00%> (+3.72%)	⬆️
postgrest_py/_sync/client.py	89.65% <80.00%> (+16.12%)	⬆️
postgrest_py/base_request_builder.py	78.14% <97.56%> (-0.08%)	⬇️
postgrest_py/__init__.py	100.00% <100.00%> (ø)
postgrest_py/exceptions.py	51.85% <100.00%> (+8.37%)	⬆️
tests/_async/test_client.py	100.00% <100.00%> (ø)
tests/_sync/test_client.py	100.00% <100.00%> (ø)
... and 1 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 9ddc6f5...6607674. Read the comment docs.

[J0]

Lorn, thanks for putting this together!

[J0]

Is this still relevant?

[anand2312]

Whoops, didn't mean to leave that in. Good catch, reverted in 300a089

[sourcery-ai]

Sourcery Code Quality Report

❌  Merging this PR will decrease code quality in the affected files by 0.67%.

Quality metrics	Before	After	Change
Complexity	0.62 ⭐	0.81 ⭐	0.19 👎
Method Length	25.75 ⭐	26.07 ⭐	0.32 👎
Working memory	5.46 ⭐	5.47 ⭐	0.01 👎
Quality	89.26% ⭐	88.59% ⭐	-0.67% 👎

Other metrics	Before	After	Change
Lines	748	1005	257

Changed files	Quality Before	Quality After	Quality Change
postgrest_py/base_request_builder.py	87.91% ⭐	87.86% ⭐	-0.05% 👎
postgrest_py/exceptions.py	84.75% ⭐	84.75% ⭐	0.00%
postgrest_py/_async/client.py	92.94% ⭐	96.07% ⭐	3.13% 👍
postgrest_py/_async/request_builder.py	88.32% ⭐	84.42% ⭐	-3.90% 👎
postgrest_py/_sync/client.py	92.98% ⭐	96.10% ⭐	3.12% 👍
postgrest_py/_sync/request_builder.py	88.35% ⭐	84.47% ⭐	-3.88% 👎
tests/_async/test_client.py	92.32% ⭐	92.39% ⭐	0.07% 👍
tests/_sync/test_client.py	92.32% ⭐	92.61% ⭐	0.29% 👍

Here are some functions in these files that still need a tune-up:

File	Function	Complexity	Length	Working Memory	Quality	Recommendation

Legend and Explanation

The emojis denote the absolute quality of the code:

• ⭐ excellent
• 🙂 good
• 😞 poor
• ⛔ very poor

The 👍 and 👎 indicate whether the quality has improved or gotten worse with this pull request.

---

Please see our documentation here for details on how these metrics are calculated.

We are actively working on this report - lots more documentation and extra metrics to come!

Help us improve this quality report!

[anand2312]

@J0 I tried deploying to RTD but I seem to not have enough permissions on this repo (it needs permissions to manage webhooks). Can you try?

[J0]

Weird, I'll look into getting you those permissions. One sec.

Hmm seems like it was successfully deployed: https://postgrest-py.readthedocs.io/en/latest/api/filters.html

lmk if this is still an issue! Btw, we should probably change the library namespace to postgrest before we advertise the docs

[anand2312]

@J0 the deployed version is pointing to my fork right now, not this repo. I did that because I couldn't get the config files just right so I needed to test first 😅 I'll move it here in a bit once I get the permissions. Or you could send me your readthedocs account name and I'll add you as a maintainer, and then you could set up the webhook (the webhook is to automatically deploy updated documentation when new commits are made)

[anand2312]

Alternatively, we can deploy docs to Github Pages intead of readthedocs. The domain name would then be https://supabase-community.github.io/postgrest-py/
Pro: having everything coupled to this repo would be convenient
Con: Readthedocs offers versioned docs by default which could be quite nice