Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
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 (
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.
@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
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.
You raise a really good point about
The point about having documentation for previous versions is quite a good one. Using
Also, having to prefix every line with
Regardless of whether we use
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
Also, in general how does
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.
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.
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?