Website: add Examples by pulling in hyper repo `examples` directory

[Michael-J-Ward]

Could you clarify what you mean by "pullling in the hyper repo examples"?

• Add a link to the examples folder in the guide sidebars after the link to API Reference?
• Create guide-like equivalents for each example?
• Something else using some jekyll feature

[seanmonstar]

I had this idea when I ran across the curl examples. I guess thinking more about it, I'm not sure there's a lot of added value having the code rendered separately, but perhaps just having a list and description of examples linking to them is enough? I'm not sure...

My vague goal is to improve the onboarding experience for new users :)

[Michael-J-Ward]

So, the easy / immediate thing is to copy / polish the example's README to the website.

For some inspiration towards the deeper goal, the clap team did a deep dive on documentation options geared for guides, tutorials, and examples. Here's the summary post of the thread. They chose a few nifty "hacks" to get cargo-checked cookbook examples and guided tutorials included on docs.rs.

cargo-crev used a similar technique for their own.

So, my suggestion is that I do the easy thing now and close this ticket. And if that discussion interests you in some other option, I can explore that later. Sound good?

[seanmonstar]

They chose a few nifty "hacks" to get cargo-checked cookbook examples and guided tutorials included on docs.rs.

While those options are clever, I think that since we do have a website that can be structured more than docs.rs, we should take advantage of it.

the easy / immediate thing is to copy / polish the example's README to the website. my suggestion is that I do the easy thing now and close this ticket. And if that discussion interests you in some other option, I can explore that later. Sound good?

I think so, yes. I do lean towards coming up with a way to regularly/automatically import that README, so that it doesn't grow outdated, nor need fixes merged to two places.

[Michael-J-Ward]

While those options are clever, I think that since we do have a website that can be structured more than docs.rs, we should take advantage of it.

I'm not suggesting to eliminate hyper.rs. rustdoc can be published to your own domain, like tracing.rs does. The other main option the clap team explored was mdbook, which I believe is what serde.rs uses.

I think so, yes. I do lean towards coming up with a way to regularly/automatically import that README, so that it doesn't grow outdated, nor need fixes merged to two places.

I agree. The closest that I achieved was to pull hyper in as a submodule, copy the hyper/examples folder into _stable, and then link to its README. While the page renders as expected, we'd need some additional processing to get the links to work. Perhaps someone more experienced with jekyll can find a better way.

So, the current best solution I found with jekyll that would keep things synced would be to link back to the repo.

- For full examples, check out the [examples collection][] in the repo.
[examples collection]: {{ site.examples_url }}

[oddgrd]

I have learned a (little) bit about jekyll working on the guides, maybe you could open a draft PR Michael and I can take a look?

[IsaacCloos]

🙋🏻‍♂️

If this issue is open to additional support, I'd like to participate 😄. I see that the thread has gone a bit quiet, but if the interest is still there, I can draft (or contribute to) a proposal, and we can workshop it from there.

I have read the contribution guidelines and have contributed similar work for projects like tabled, mirrord, and meilisearch-rust. By that, I mean beginner-friendly tasks related to documentation and examples 😅.

[oddgrd]

Sounds good to me Isaac! I think importing the examples readme like discussed above is a good place to start, perhaps with a workflow similar to contrib.yml to keep it updated. We might also want to have one readme for stable and one for legacy on the website, but we could start with just the 1.0 example readme and then link to 0.14 in there for people looking for that. :thinking: Currently the example readme on master (hyper 1.0) lists hyper 0.14 as a dependency, so that would need to be updated as well (in this repository). I'm happy to answer questions if you have them, but I may be a bit slow to reply. :pray:

[IsaacCloos]

I believe after reading through this discussion I've got 2 separate issues to address.

Examples + hyper.rs

I've picked out two significant quotes above.

I guess thinking more about it, I'm not sure there's a lot of added value having the code rendered separately, but perhaps just having a list and description of examples linking to them is enough? I'm not sure...

I think so, yes. I do lean towards coming up with a way to regularly/automatically import that README, so that it doesn't grow outdated, nor need fixes merged to two places.

Of course, the first thing that comes to mind, as counseled by @oddgrd, could be to create a new cron job similar to contrib.yml, or to rename that job to make it more general and consolidate all 'hyper to hyper.rs' steps in one place. That could do the trick nicely. As stated, there may be additional requirements such as hosting both stable and legacy READMEs, etc.

However, I have a preliminary pitch advocating for simplicity, hosted from my fork. By utilizing the available site metadata, I added a new link in the guide sidebar to the corresponding example READMEs on GitHub. These links are already organized, are always up-to-date, and do not attempt to re-render code. Please give that demo a try (visit the guides/1 and guides/0.14), and let me know what you think 😄. (The link text can be anything you'd like of course)

If you're set on bringing over the README.md files just let me know and I'll draw up the changes discussed above 👍🏻.

Inaccuracies with examples/README

This was a curious extra tidbit mentioned by @oddgrd that ended up sucking me down an example rabbit hole 😅.

https://github.com/hyperium/hyper/blob/d4295eb976ef424939797f7e3f1e2d85aee8b224/examples/README.md?plain=1#L11-L16

Line 13 is indeed no longer accurate for the master branch, resulting in several references to v1.X features failing. However, that's not all that's incorrect, or rather missing. If you tally up all of the necessary dependencies (across all the 1.0 examples) the following would also need to be included:

bytes
http_body_util
serde
futures_util
url

I know the obvious answer feels like 'OK, add these too.' But is it? What is the point of telling someone what packages they need to install to run these examples? Are the examples supposed to be followed like guides, or do they only serve to aid those who have cloned the repository? In that case, they would already have the necessary dependencies in their TOML file.

I think it comes down to: A. Extend the dependency list to give complete coverage for people following along in separate projects. B. Remove the section and lean into the examples being a resource for those who have cloned the project.

---

Thank you so much for your valued feedback. It makes a world of difference to me 😄

[oddgrd]

Thanks Isaac! I quite like your idea of just having the Additional Examples link, thanks for the detailed write-up and the preview website, that's really great. :heart:

As for the examples readme dependencies, it's a bit tricky. They're meant to be run with examples commands after cloning the repo, but people will use them directly as well. So just having a list of all the dependencies used in examples seems useful to me! Might spare some people some confusion.

@seanmonstar what do you reckon on these points?

[seanmonstar]

Having a link to "Additional Examples" seems like a good compromise, I like it!

[seanmonstar]

Closed by https://github.com/hyperium/hyperium.github.io/pull/93