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

Add Documentation #137

Merged
merged 8 commits into from Feb 25, 2021
Merged

Add Documentation #137

merged 8 commits into from Feb 25, 2021

Conversation

KyGost
Copy link
Contributor

@KyGost KyGost commented Dec 15, 2020

WIP

@KyGost
Copy link
Contributor Author

KyGost commented Feb 19, 2021

Looks like I already had a draft PR.

What needs to be added before merge?
Sorry it has been sitting here for so long.

@KyGost KyGost marked this pull request as ready for review February 19, 2021 02:14
@panarch panarch self-requested a review February 19, 2021 14:18
@panarch panarch added documentation Improvements or additions to documentation enhancement New feature or request labels Feb 19, 2021
Copy link
Member

@panarch panarch left a comment

Choose a reason for hiding this comment

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

Again, please feel free to participate :)
And wow you also added an error guideline, thanks so much!

Looks very good to start!

There is an one stuff I request you to change,
Because of end-of-line issue, GitHub Action failed on cargo fmt

Then, I'll merge this and make it accessible via https://gluesql.org/book

I'm considering to use https://github.com/marketplace/actions/mdbook-action to automate

@KyGost
Copy link
Contributor Author

KyGost commented Feb 23, 2021

@panarch thoughts on what to do about this check error?

@panarch
Copy link
Member

panarch commented Feb 24, 2021

@KyGost It would be the issue of your editor. cargo fmt doesn't solve this? then.. I think editing those files in github.com web editor might work.

@KyGost
Copy link
Contributor Author

KyGost commented Feb 24, 2021

@panarch rustfmt worked this time but the tests failed because of the example code, have a look at the fail details.

@panarch
Copy link
Member

panarch commented Feb 24, 2021

@KyGost Ok, I think I got it if.. you are using Windows.

Can you try cargo fmt again after adding file with rustfmt.toml to the root of the repository?

In rustfmt.toml,

newline_style = "Unix"

Or... it might be related to the cargo version.
I'm using 1.50.0 (2021-02-04) and when I run cargo fmt using your branch, then it shows that cargo fmt fixes EOL.
image
I used Linux (Ubuntu 18.04) for this.

@KyGost
Copy link
Contributor Author

KyGost commented Feb 24, 2021

The issue coming up when I check the error on the commit is:

error[E0432]: unresolved imports `gluesql::Glue`, `gluesql::SledStorage`
 --> examples/hello_world.rs:1:22
  |
1 | use gluesql::{parse, Glue, Payload, SledStorage, Value};
  |                      ^^^^           ^^^^^^^^^^^ no `SledStorage` in the root
  |                      |
  |                      no `Glue` in the root
  |                      help: a similar name exists in the module: `glue`

@KyGost
Copy link
Contributor Author

KyGost commented Feb 24, 2021

The EOL issue is annoying too, I'll play around with some settings and try to fix that at some point.

Looks like the main issue however is that one references glue differently externally to how it is referenced internally.
This seems to be causing the issue here, the tester is for some reason testing the example code.

How can I get the tester to ignore the examples?
@panarch

@panarch
Copy link
Member

panarch commented Feb 25, 2021

@KyGost ok, I can say what's going on in here.

The issue coming up when I check the error on the commit is:

error[E0432]: unresolved imports `gluesql::Glue`, `gluesql::SledStorage`
 --> examples/hello_world.rs:1:22
  |
1 | use gluesql::{parse, Glue, Payload, SledStorage, Value};
  |                      ^^^^           ^^^^^^^^^^^ no `SledStorage` in the root
  |                      |
  |                      no `Glue` in the root
  |                      help: a similar name exists in the module: `glue`

gluesql::Glue and gluesql::SledStorage are exported only if sled_storage feature is enabled.
These are optional because it is not required for making a custom storage, only useful for standalone use.

In Cargo.toml,
image

For convenience, I enabled sled_storage feature by default.
So, someone who simply wants to use GlueSQL like SQLite, they can import and use it based on SledStorage. They don't need to care anything about features.
However, for custom storage makers who doesn't need SledStorage, they can import gluesql with sled_storage disabled.

And tests should work both with features & without features.
In .github/workflows/rust.yml
image

I included several cargo test cases.
without features, using sled_storage, using alter_table, and using both sled_storage and alter_table.

Your examples require sled_storage feature, so you need to use cfg macro.

Style is up to you.
If you change your example file like this below, then it will not make noise.
https://gist.github.com/panarch/48bf217c46938ca6484eea9f6d649956
or you can see examples/api_usage.rs or examples/using_config.rs.

@KyGost
Copy link
Contributor Author

KyGost commented Feb 25, 2021

@panarch ahhh okay, thank you very much.

Something different seems to have failed now though...? :-(

@panarch
Copy link
Member

panarch commented Feb 25, 2021

@KyGost 👍
I think your last commit will also fail.
#[cfg(feature = "sled-storage")] this is only applied to the next line.

fyi. https://doc.rust-lang.org/reference/attributes.html

So, in examples/hello_world.rs

#[cfg(feature = "sled-storage")]
use gluesql::{parse, Glue, Payload, SledStorage, Value};	use gluesql::{parse, Glue, Payload, SledStorage, Value};

It only excludes use line but those are used in fn main() { ... } so it cannot be compiled.

@KyGost
Copy link
Contributor Author

KyGost commented Feb 25, 2021

Oh I see, I need to use

#[cfg(feature = "sled-storage")]
mod sled_multi_threaded {
...
}

Thanks

@KyGost
Copy link
Contributor Author

KyGost commented Feb 25, 2021

@panarch it should work now but now includes needless items in the book. How can we avoid this? Is there a way to add the rules to the file outside of the file?
image

@KyGost
Copy link
Contributor Author

KyGost commented Feb 25, 2021

Looks like it failed again....

Was the strictness increased recently?
Looks like it is failing on other ~/executor/ things, which haven't been changed in this PR and should have passed previously.

@panarch
Copy link
Member

panarch commented Feb 25, 2021

Looks like it failed again....

Was the strictness increased recently?
Looks like it is failing on other ~/executor/ things, which haven't been changed in this PR and should have passed previously.

Oh, I just tested and found that. I'm simply using the default setting of clippy, it looks like it is because of recent cargo updates.
I'll take this and make it lint-clean again till tomorrow, then I'll merge to main then please merge this to this branch. Then GitHub Action cargo clippy will pass.

@panarch
Copy link
Member

panarch commented Feb 25, 2021

@panarch it should work now but now includes needless items in the book. How can we avoid this? Is there a way to add the rules to the file outside of the file?
image

That make sense.
I also need to figure out the way to make it better.

We might solve this by editing Cargo.toml.
If we can make cargo to ignore examples/ when sled_storage feature is disabled, then it would be cool.

Let me know you found something, I'll also try to figure out.

@panarch
Copy link
Member

panarch commented Feb 25, 2021

@KyGost #142
Tomorrow is too far from now.
Now main branch is clippy clean :)
Please merge and try again 👍

@KyGost
Copy link
Contributor Author

KyGost commented Feb 25, 2021

@KyGost #142
Tomorrow is too far from now.
Now main branch is clippy clean :)
Please merge and try again 👍

Awesome! I'll rebase.

@KyGost
Copy link
Contributor Author

KyGost commented Feb 25, 2021

@panarch woohoo! Tests passed.

@panarch panarch self-requested a review February 25, 2021 12:04
Copy link
Member

@panarch panarch left a comment

Choose a reason for hiding this comment

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

@KyGost Awesome 👍 👍 👍
I'll merge and build & upload to https://gluesql.org/book soon!

About making this implicitly, let's do it in another pr.
image

Thanks!!

Copy link
Member

@panarch panarch left a comment

Choose a reason for hiding this comment

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

@KyGost Awesome 👍 👍 👍
I'll merge and build & upload to https://gluesql.org/book soon!

About making this implicitly, let's do it in another pr.
image

Thanks!!

@panarch panarch merged commit 25c7dd1 into gluesql:main Feb 25, 2021
@KyGost KyGost deleted the documentation branch February 26, 2021 04:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants