dcmoura / spyql

Query data on the command line with SQL-like SELECTs powered by Python expressions
https://spyql.readthedocs.io
MIT License
918 stars 25 forks source link

Full-featured documentation #80

Closed dcmoura closed 2 years ago

dcmoura commented 2 years ago

This PR proposes a brand new documentation. This PR closes #34 .

Please ignore the commits... the history of this PR is quite disturbing 😅 Everything will be squashed into a single commit when merging to master.

Please focus on 1) the structure and then 2) the content of:

I am proposing deprecating the -> operator. It will still be supported but is not mentioned in the documentation. From now on, the . (dot) operator should be the standard way of accessing fields in dicts, followed by standard Python syntax (a_dict["key"]). Major drawback is that we will need to do a new video demoing the CLI and update some posts (e.g. stack overflow).

There is still some work to do on the lib side. Namely, we should add a section under Examples/Recipes. However, there is still some dev work to do, namely on accessing Pandas dataframes and series, as well as numpy arrays. Eventually we can also visit polars and other libs for tabular data. When we do that, we can extend the documentation.

In this first review let's try to focus on the big fish, and not so much on the details. My goal is to publish the documentation soon, and then we can iterate on it over time. Thanks!

codecov[bot] commented 2 years ago

Codecov Report

Base: 95.63% // Head: 95.63% // No change to project coverage :thumbsup:

Coverage data is based on head (8f1911a) compared to base (1c1874d). Patch has no changes to coverable lines.

Additional details and impacted files ```diff @@ Coverage Diff @@ ## master #80 +/- ## ======================================= Coverage 95.63% 95.63% ======================================= Files 15 15 Lines 1284 1284 ======================================= Hits 1228 1228 Misses 56 56 ``` | [Impacted Files](https://codecov.io/gh/dcmoura/spyql/pull/80?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Daniel+Moura) | Coverage Δ | | |---|---|---| | [spyql/agg.py](https://codecov.io/gh/dcmoura/spyql/pull/80/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Daniel+Moura#diff-c3B5cWwvYWdnLnB5) | `98.24% <ø> (ø)` | | | [spyql/nulltype.py](https://codecov.io/gh/dcmoura/spyql/pull/80/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Daniel+Moura#diff-c3B5cWwvbnVsbHR5cGUucHk=) | `87.67% <ø> (ø)` | | | [spyql/query.py](https://codecov.io/gh/dcmoura/spyql/pull/80/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Daniel+Moura#diff-c3B5cWwvcXVlcnkucHk=) | `97.95% <ø> (ø)` | | | [spyql/sqlfuncs.py](https://codecov.io/gh/dcmoura/spyql/pull/80/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Daniel+Moura#diff-c3B5cWwvc3FsZnVuY3MucHk=) | `93.33% <ø> (ø)` | | Help us with your feedback. Take ten seconds to tell us [how you rate us](https://about.codecov.io/nps?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Daniel+Moura). Have a feature suggestion? [Share it here.](https://app.codecov.io/gh/feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Daniel+Moura)

:umbrella: View full report at Codecov.
:loudspeaker: Do you have feedback about the report comment? Let us know in this issue.

dcmoura commented 2 years ago

What a great job Daniel 👏 🎉 I'm sorry if most of these comments are just small nitpicks but that's a really good sign 😜 The only major thing is the reference section not being rendered correctly (see #80 (comment))

Thank you @recharte, this is great feedback! The reference section is rendering fine locally, I will check what's happening in readthedocs.

dcmoura commented 2 years ago

@recharte Just finished going over your remarks, thanks!