Tutorial

[vorner]

This kind of library would really benefit from a tutorial how to use it.

There's one here, but it is outdated: https://vorner.github.io/2018/12/09/Spirit-Tutorial.html. There are some examples in the repository (examples/hws-complete.rs is probably the richest one).

Rough ideas:

• Start with spirit-less example (simple TCP echo server or message-of-the-day server is enough).
• Step by step add support for spirit, logging, metrics, reloading of the listening ports...

To prevent it from getting outdated, it might be a good idea to create a dummy module that has no code, but only the tutorial as one big doc-comment. This way it will not only be in the repository and the examples and code snippets will be compiled & checked, but it'll also render on docs.rs.

If someone wants to give it a try, please claim the issue. I'll provide any help or guidance necessary. If you don't have that much experience with Rust or the spirit library, that's probably even better as you have better idea what you need to know.

[Michael-F-Bryan]

@vorner I wouldn't mind giving this a shot.

I feel like mdbook would be a good platform for this. Instead of creating a dummy module, you could make a set of programs inside the example/ folder, then use the include portions of a file function to insert snippets into the guide while using CI to make sure the original examples still compile.

[vorner]

Hello

Thank you that you're looking into this. I'll assign the task to you.

The reason I don't really like mdbook much is, besides having to host it somewhere and setting up the CI and everything, it necessarily covers only the current newest version. I find some value in the fact that even older versions would have their own versions of tutorial relevant for them. Furthermore, books tend to end up quite long and I hoped to something of moderate length. But I'm OK listening to arguments why mdbook would indeed be better.

I've noticed you've already sent a pull request, which is great. I'll find the time to look through it during the next few days.

[Michael-F-Bryan]

You raise a really good point about mdbook in that it tends to promote lengthier documents when a shorter one would suffice. I guess the only way to counteract that tendency is by having conciseness as a goal and being quite aggressive about it during code review?

The point about having documentation for previous versions is quite a good one. Using rustdoc essentially gives tutorial versioning to you for free, whereas mdbook tends to promote a "living" document which reflects how things are done on the current master (not latest release). Although with the popularity of tools like cargo outdated I would question how common it is to be stuck on an older version of a library?

Also, having to prefix every line with //! and having Rust syntax highlighting when you're writing Markdown might get annoying.

Regardless of whether we use mdbook or rustdoc, the tutorial will probably consist of a handful of Markdown pages (one big page might get a bit hard to maintain?) and switching between the two will be a case of inserting/removing //! from the start of every line.

---

In terms of the tutorial itself, is there an outline of the areas we'd like to touch on? The original blog post gives us a strong foundation to build from, although looking at the API docs there's quite a large ecosystem of crates which can be plugged into spirit to provide nice things (dipstick, reqwest, hyper, etc).

Also, in general how does spirit work with existing tools like systemd? I'm guessing you'd just need to write a small systend unit file and everything would Just Work, but it's worth mentioning how to install spirit applications as an OS-level service.

[vorner]

I would question how common it is to be stuck on an older version of a library?

I don't know. I've done some changes between versions that need non-trivial porting. If there was a company that had some (unpublished) spirit-something plugins and the company wouldn't be very fast in porting, it might be convenient for new employees to have the relevant tutorial somewhere. But I guess as it being tutorial that is aimed at new users, having to use older version is probably rare.

In terms of the tutorial itself, is there an outline of the areas we'd like to touch on? The original blog post gives us a strong foundation to build from, although looking at the API docs there's quite a large ecosystem of crates which can be plugged into spirit to provide nice things (dipstick, reqwest, hyper, etc).

I'd propose starting with as little as possible, just enough to explain the principles. Using specific crates once the principles are known should be matter of API documentation.

But if it turns out putting more in the tutorial is advantageous, it can be added in later versions.

Also, in general how does spirit work with existing tools like systemd?

I don't think there's a specific support needed. I don't use systemd myself, but from what I know about it, just writing the service file should be enough. For older init systems, spirit-daemonize should give everything needed.

If there's something special needed for systemd, it should be hopefully possible to add as some spirit-systemd crate. If you know about anything specific, would you create an issue?

[vorner]

Hello, @Michael-F-Bryan. I wanted to check ‒ do you plan on continuing with the guide? There was some silence time 😇.

[vorner]

Cleaning up: we do have tutorial now, in the docs.rs pages.