Add getting started guide

[Thomasdezeeuw]

No description provided.

[dtacalau]

Looks good apart from one missing word.

[kleimkuhler]

I really like the idea of adding this! Is nesting a guide within a crate module a common practice though? I have not seen it before. If a user didn't know it was there--or even to look for it--it doesn't seem that easy to find.

When the documentation is built, it also looks a little odd to have guide listed as a module along with event, net, and unix. I think modules should be used strictly for scoping functionality, not necessarily a getting started guide? Let me know your thoughts though I'd really like to add this in some way!

[Thomasdezeeuw]

Is nesting a guide within a crate module a common practice though? I have not seen it before.

Not sure, but as you mentioned in #1133, doc.rs/these API docs are one of the sources new users look first. This also has the added benefit of running the examples as tests for us.

If a user didn't know it was there--or even to look for it--it doesn't seem that easy to find.

I'll add a section to the made docs for this.

When the documentation is built, it also looks a little odd to have guide listed as a module along with event, net, and unix. I think modules should be used strictly for scoping functionality, not necessarily a getting started guide? Let me know your thoughts though I'd really like to add this in some way!

We could rename guide to docs and have longer form documentation in there, including a sub-module guide.

[carllerche]

@Thomasdezeeuw You can probably just make a docs dir in the repo and use .md files... You can use that strategy if you want. I don't think we should add a pub module though.

Re: API doc usability. Scrolling on the entry point never really bothered me. I always hit S and search.

[Thomasdezeeuw]

@Thomasdezeeuw You can probably just make a docs dir in the repo and use .md files... You can use that strategy if you want. I don't think we should add a pub module though.

The problem with regular .md is that the code is never tested. All documentation inside the code it tested automatically ensuring it keeps up to date.

As for other crates that use docs.rs for additional docs (such as guides): https://docs.rs/snafu/0.6.0/snafu/guide/index.html.

But if everybody else agrees that this isn't the place for it I'll move it a doc directory.

[hawkw]

@kleimkuhler

I really like the idea of adding this! Is nesting a guide within a crate module a common practice though? I have not seen it before. If a user didn't know it was there--or even to look for it--it doesn't seem that easy to find.

FWIW, I think having the guide in the RustDoc is a good idea for discoverability, since most people tend to start on docs.rs these days, and it's often hard to find external docs from within RustDoc. For example, I don't think tokio's API docs ever refer to the guides at tokio.rs/docs. I've definitely seen other crates do similar things, such as snafu (mentioned above) — I've done something similar for some notes on implementation details that started to get kind of lengthy.

Additionally, it has the significant advantage of ensuring that the examples don't get out of date and are built alongside every change. I think that's worth a lot, to the extent that I've been considering removing code samples from tracing's README and putting them into the RustDoc.

IMO, putting guides in the RustDoc is a good approach for mio. Personally, unless this content is extremely long, I think it's fine to have it in the top-level crate docs. If it's long enough that modules are necessary, I think it's important for the crate-level docs to highlight the existence of the modules.

[kleimkuhler]

@hawkw Thanks for the thoughts on this!

@Thomasdezeeuw I also would like for the examples to still be tested so that they do not fall out of sync. I would be concerned about moving them into separate .md files.

With the comments above pointing out some other crates that have done something similar and the benefits of doing so, I would be okay with this change going through!

With the points made here though, I'm not sure I agree with the proposed changes in #1133 about moving the example to an .md file. I don't think the README is as discoverable as what renders on docs.rs and it's possible for the example to get out of sync. Could we consider making the example smaller?

[carllerche]

Testing of arbitrary md files can be handled with: https://github.com/budziq/rust-skeptic

if a separate guide module stays, I would ask that it be conditionally defined using a doc using a --cfg flag or something. This is a pattern used here (which we will probably need to do for #1123 anyway).

[Thomasdezeeuw]

I've added a new "guide" feature (disable by default, enable on docs.rs) and put the user guide behind it.

@carllerche I perosnally don't really like the idea of even more tools to run ours tests. I hope the latests change is good enough for you.

[Thomasdezeeuw]

I'm merging this even though there is no consensus. I think we should try it this way, if we come to the conclusion it sucks we can move it to a docs directory.