Feature Request: Incorporating the blogs into official documentation

Lockszmith-GH commented 3 years ago

The Blog series at https://didrocks.fr/ is excellent.

I hope on of the suggestions would be agreeable with you:

Copy all of the blogs to the wiki.
Making sure ALL relevant blog articles are tagged with ZSYS: Have the README.md and the wiki Home-Page (or just disable the Wiki) point to the blog's tag, so that everything will be referenced from here - I only found about the blog site from the issues.
Since I understand that one of the goals was to have the system be completely self documented, with everything embedded within the source code, creating a 'docs' sub-command where the system is explained (with the blog posts being imported - as best as possible in a cli/ansi output as possible)

I am willing to take the task upon myself (you already did all the heavy lifting of writing the content) and put the content wherever you want, just choose the approach that suites you, and I'll be happy to accommodate. If #1 is the approach you want to take, keep in mind GitHub doesn't provide a PR workflow for wiki.

Let me know if I can help.

didrocks commented 3 years ago

Thanks for the suggestion and the feedback on the blog posts! I think 1 or 3 would make sense (I don’t think having the documentation "externally" is really a good practice, indeed).

is really tempting. I’m unsure i have the time for that task, but I don’t think it’s too complicated to do it for a newcomer, would you be interested in that task? (We can even imagine having some CI to automate the extraction of the doc from the command and populate/refresh the wiki here as we do for the README.md command list). However, if we go with 3. there is the image situation to take into account: how big would that impact the binary size? What format do we output for the documentation and still having the images reachable? Should we just keep them?

A lot of questions to be answered before choosing one strategy over the other :)

Btw, the source of the blog post are in markdown and available at https://github.com/didrocks/website (more specifically https://github.com/didrocks/website/tree/master/content/blog)

Lockszmith-GH commented 3 years ago

@didrocks the fact that the source of the blogs are in markdown makes everything even easier (I think) As for images, we can always put a link to the a file in github, and create an ascii art version of it (like RFC docs)

I'll take a stab at incorporating the text into the code, and send a PR when I'm done (might start with one or two, at first)

Lockszmith-GH commented 3 years ago

OK, I got a draft with a raw dump of the What's New. I'll edit it, but I wanted to get your OK on the direction. (also: Is this the best place to have this discussion?)

Here it is: https://github.com/Lockszmith/zsys-fork-for-pr/blob/documentation/cmd/zsysd/client/docs.go

didrocks commented 3 years ago

Great! Thanks for working on it! I just had a look, some feedbacks:

First, yeah, a separate file for handling this doc command is good :)
On the subcommand organization: how would I know that "What’s new" should be read before the second part and so on? As there are some ordering that is important to follow the doc, I really wonder (opened question) how can we guide the user to follow a certain order…
I would refrain from embedding a copy directly in a .go file: it’s hard to edit/fix. Can we have that as a .md file and embedding that when compiling? If you look, this is what we do for po file (so, we still have a single binary to deploy). Go 1.16 (released in the coming days) has a very easy way for that: https://lakefs.io/working-with-embed-in-go/. Basically, we will be able to do:
```
import _ "embed"
```

//go:embed what-new.man var whatNewContent string


And then, we can simply `fmt.Println(whatNewContent)`. The original is not needed in the finale binary.
I have no issue with waiting for 1.16 to be released for this (and we can put all docs in a separated single directory in the repo).
- the buffer isn’t useful in that case, just print the output directly. However, I would find really cool if we can have a pager-like behavior, this systemd or other commands:
   - if the doc is only a file line longs, the output is printed directly
   - if the doc is longer (multi pages), the output is wrapper in some kind of `less` behavior.
   I don’t know how hard that is (I didn’t check any golang packages that do that, but I think one should be around). Not mandatory, but would be a nice to have :)

What do you think?

Lockszmith-GH commented 3 years ago

All of the points are ones I've been thinking about as well.

Sub-commands, as I see it, there are 2 options:

instead of 'whatsnew', naming it 'a_whatsnew' or '00_whatsnew' - ugly as hell, but it will keep the order.
alternativley, name it just 'a' or '00' with an alias of 'whatsnew' - less ugly, but still not very pretty.

I love the embedded solution, I didn't know about it, and from what you're writing it seems it's not available yet, but yes, that's exactly what we should do, I'll read up on that now.

Noted about the buffer, and totally agree on the paging. This troubled me as well, I think I'll use more as it's part of POSIX, so we can expect it to be there on any system, maybe check for the existence of less and use that if it's there.

didrocks commented 3 years ago

On numbering, I think if we can sightely rephrase the content to be mainconcepts, taking also the bionic posts (I guess the others are fine as more "per topic") and that way, this is less shocking :)

The embedded solution is going to be ready with Go 1.16, which should be out in the coming days, so, let’s just be patient :)

Ack on using more, I wonder just if there is a go package to deal with that directly instead of redirecting the output outself… Needs investigation :)

Lockszmith-GH commented 3 years ago

Just to keep track: https://stackoverflow.com/questions/28705716/paging-output-from-go

Lockszmith-GH commented 3 years ago

Pager used, detection with a fuzzy decision on activating it. Do you have any suggestions on rendering text to console? I can't seem to find one that already does it, but I'm also not very well versed in the golang universe (this is the first REAL go project I'm contributing to)

Link is still: https://github.com/Lockszmith/zsys-fork-for-pr/blob/documentation/cmd/zsysd/client/docs.go

didrocks commented 3 years ago

Excellent! Happy for you that you go into go (pun intended) universe a little bit more :)

I had a quite look at your current work, generally, it seems to be exactly what is needed, some comments:

Waow, I see you are already using the embedeed tag, are you using golang beta 1.16?
I think you can remove some comments from the code, like the command output changes and so on.
The wrapping library looks good.
Be aware that you deleted (probably by mistake) go.mod and go.sum.

As an additional bonus, I think the general "doc" command should (without any argument) display all available documentation (and ofc, documentation needs to be available in the completion).

On rendering text into console, it really depends on what you want to do, if this is only some bold/color work, I suggest using github.com/fatih/color. We used it recently in another project if this can inspire you: https://github.com/ubuntu/adsys/commit/91e6ebe2554ca37f33a086ac2b9bce1e79139d0e#diff-05529814acc78041529e208ce08bacfbec4f060f8508abedeaa71c732f179492R83 (usage of bold and some colors)

Lockszmith-GH commented 3 years ago

yes, I'm doing all of this in a docker container, and since I wanted to test out the embedding, I just went ahead and installed go 1.16 via:

go get golang.org/dl/go1.16rc1
go1.16rc1 download

And I'm building now with:

go1.16rc1 build ./...

I'll take a look at using github.com/fatih/color as well as your use in adsys, I'll update here when I have something in place

dcarosone commented 3 years ago

TIL from this issue that zsys is documented in a series of blog posts. I noted in #207 that I have no idea what zsys is trying to do, in detail. Until now, all I had seen was the command-usage stuff in the manpage and repo README - nothing about intent or objectives or approach.

While I agree with this issue that these docs should migrate to a better home in the repo, to be updated as further development occurs..

In the meantime, can we PLEASE have a set of links to the blog posts at the top of the README, so that at least they are discoverable. I'm off to go read now, but I'd have been much happier to have found these when they were written or when I came here to look previously.

didrocks commented 3 years ago

That’s a good one, added to the README. Thanks

ubuntu / zsys

Feature Request: Incorporating the blogs into official documentation #188