-
Notifications
You must be signed in to change notification settings - Fork 332
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
use markdown for the documentation #1474
Conversation
I think this is a great idea! The idea of using https://pkg.go.dev/ to host documentation has always seemed strange to me given that A few points of discussion from me:
Otherwise I don't really have much more to add - this is a welcome change for both contributors and maintainers. |
There are several projects that have Markdown-like syntax that is designed to be converted to a man page. One example is https://github.com/rtomayko/ronn. I like it, except for the fact that it requires installing Ruby. (Update: Also, it seems to be minimally maintained) There are others, I will add them to the thread if/when I remember what they are. Ranger uses https://perldoc.perl.org/pod2man which is Perl-y and not Markdown. OTOH, pandoc is great, and we could compromise on how canonical the man pages are to get its other benefits. There's a template (not sure how perfect) at https://eddieantonio.ca/blog/2015/12/18/authoring-manpages-in-markdown-with-pandoc/. |
Here's the other alternative I encountered that seemed interesting. It comes from the suckless world, which might be a good philosophy for this purpose. I'll update this if I remember which project I stumbled on used https://drewdevault.com/2018/05/13/scdoc.html |
@joelim-work I tried changing our markdown to be more idiomatic as a man page. I also tried using the plain text output of @ilyagr I have looked at the alternatives you mentioned. For some reason, Lastly, I looked at the pandoc workflow, but I'm not sure if it is possible to add generated artifacts to the repository. For now, I think I will be generating the documentation manually on my machine before new releases. I'm marking the PR as ready for review. Now that we are using markdown, there are many changes that can be done, but I think they can be done separately afterwards. I'm sure you and others have better ideas than me to make the documentation more useful and pretty. |
Overall the PR looks good to me. I agree with leaving formatting improvements for future changes. I think you might have forgotten to remove The only other concern I have is the idea of keeping automatically generated files (i.e. the man page and text forms) in source control. This is actually a slightly controversial topic, though I think it's fine if you want to manually generate and commit the files before each release. I considered not storing them in the repo, and instead only generating them during the |
@joelim-work Sorry for the mess as I wasn't paying much attention. I think I have cleaned up a little bit. Note, I'm also not too satisfied with the generated files in general. Not storing them in the repo sounds interesting. I will think about it when I find some time. |
@gokcehan I suspect you might have to keep For Anyway I think the changes here are fine for now, and already an improvement over the current implementation. I will approve the PR. |
@joelim-work I have given this some more thoughts today, but I still couldn't make up my mind. There are two complications that prevents me to remove the generated files: First, we need a Second, any such change in the repo structure will technically be a breaking change for package maintainers. So if we decide to go down this route, it might be a good idea to think about a deprecation strategy along with it, or otherwise most packages will be broken in the next release. On the other side, it is not too difficult to generate the files before the release. The only difficulty is that we may forget to do so, but hopefully not. It might be useful to add a All in all, I think I will just merge this patch for now, but feel free to continue the discussion here or elsewhere for a possible change in a separate PR. |
cc #1018
This PR changes the documentation to use markdown instead of go doc.
Online markdown
Man page conversion (to be
lf.1
):Plain text conversion (to be embedded in the binary):
Rendering the markdown with
glow
(optional):or just:
Our current documentation system has become a pain point and I have been thinking of renovating it for a while. I want to make some mental notes here to help with the decision for a replacement documentation system. Feel free to join the discussion.
Our current documentation system has the following advantages/disadvantages:
gen/man.sh
is a hack and it has quirks.gen/man.sh
does not work in Windows.go generate
besides a POSIX shell.go generate
after a doc update.lf
.lf -doc
is not easily readable in a terminal.An alternative documentation system should ideally keep all or most of the advantages while also getting rid of some of the disadvantages. I'm currently thinking of simply switching to markdown for the documentation. Some notes below:
go generate
. I can then try to generate the documentation before a release myself, but ideally we could also consider setting up an automatic workflow for that (e.g. pandoc-action-example might work, not sure.)doc
command (e.g. glow).I'm currently in favor of using GFM to provide us enough features to work with. This is an experimental draft patch today to see what we can do about improving the current content in the documentation.
TODO
Try to set a workflow for automatic pandoc to man page and plain text conversions(not sure if it is possible to commit artifacts to the repo)