The Book is hardly readable

[JakkuSakura]

This book https://time-rs.github.io/book has almost nothing in it. Is it complete?

[jhpratt]

No, it's not.

[SorteKanin]

It would be helpful if the book made it clear that it is incomplete - right now the missing text seems like a bug :)

[briankung]

This deterred me from using this crate for several days trying to find the actual contents of the book. It was a lower priority so I just kept doing other things and I've only just now started to look into this in particular. I'd be happy to help document if there's a good place to start?

[jhpratt]

Incidentally I was just thinking about this last night. I think it may be preferable to inline this into crate documentation, using empty modules for hierarchy. This would make it more discoverable and more likely to be maintained once it's actually written.

If you're looking for somewhere to start, though, documenting formatting and parsing is probably the best place initially. Other than that I don't think there's a particular order that anything should be completed in.

This is, quite obviously, a low priority for me. There's development of the time crate itself, a number of RFCs that I am working on for Rust itself, and other improvements in Rust that are where I've been putting my focus. I certainly appreciate the offer to help! I assure you I will review any pull requests that are sent my way, even if they may be delayed (like the couple open now).

[laralove143]

i also think there should at least be an incomplete warning in the main page of the book and in the website https://time-rs.github.io

[egrieco]

There's a reason the US Army puts "This page intentionally left blank." in their various manuals. The book almost scared me away from this crate as well.

[jhpratt]

Everyone: I'm super busy. The website is open source. Feel free to create a pull request with the notice. Or better yet, help write some documentation 😉 Repeated comments here don't do anything.

[egrieco]

Fully understand @jhpratt. Been working on other code but I'll try to get to this in the not too distant future.

I would feel a little bit bad just adding a whole bunch of "Intentionally left blank." comments. However, now that I'm actually using the library, there are a few other code changes that might up the priority of creating a pull request.

[xy2i]

Am championning this. @jhpratt anything to keep in mind?

[jhpratt]

Not really.

[sourcefrog]

(Let me first say I absolutely understand this is maintained on a volunteer basis and this comment is posted with an intention to be useful rather than to complain.)

I also just looked at https://docs.rs/time/0.3.12/time/index.html which has no introduction to the crate but rather just begins with a list of feature flags. It makes the crate look less mature than it apparently is.

I agree that moving it into rustdoc would make it more discoverable and make the rustdoc look better, and that is probably the first thing people will find. This also does not seem like it will be such an enormous crate that it needs a separate book. Since @jhpratt says this would be acceptable in principle I might send some PRs.

[jhpratt]

No worries about tone, I fully agree!

In terms of migration to within the crate, I would prefer the book be developed in its current location first. Once it's sufficient, I can move it into this repository (possibly as a subtree, not sure).

[abuteler]

Hello and thank you for doing this work out of love and sharing it.
I'm pretty fresh on Rust, coming from more than 15 years working in the JS ecosystem, where getting the current date and time from the system is pretty straight forward, as well as parsing new dates, and then printing them out in whatever format.

When I had to pick between chrono and time, I did some reading here and there and decided to go for time-rs. Now, even though I was able to fairly quickly figure out how to get a localized OffsetDateTime and from there get the hour and minutes in u8 by using the struct's methods, I cannot for the love of me figure out how to get them to print out in a padded format with zero when the current hour/minute is just 1 digit, and it is hard to believe in this day and age that I haven't been able to find even a single example online on how doing an operation as basic as that would look like in a couple lines.

Don't get me wrong, this page in the book is amazing, but how about a working example for the less experienced?

For reference, look at chrono's documentation on how to use their format macro:
https://docs.rs/chrono/latest/chrono/struct.DateTime.html#method.format

Thanks!