Skip to content
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

Markdown in docs v1 #4158

Merged
merged 3 commits into from
Dec 2, 2022
Merged

Conversation

tertsdiepraam
Copy link
Member

@tertsdiepraam tertsdiepraam commented Nov 18, 2022

A while ago, I posted some plans for better documentation: #3181

This PR is a another step towards that plan.

After help

uudoc now supports clap's after_help, which is useful for a lot of utils. We might need to tweak what it looks like, but we can figure that out later.

Read directly from markdown file

In #3181, I created a diagram that might be useful in understanding this change. If a file like numfmt.md is available, uudoc will try to read that instead of getting its information from clap. The reason for this is that we don't want to feed clap raw markdown. Instead, we want to render the markdown to something that looks nice in the terminal. For now, I only make one simple change before handing the string to clap: removing all backticks. So now the online docs for expr can look like this:
image

while the CLI help is:

Print the value of EXPRESSION to standard output

Usage: target/debug/coreutils expr [EXPRESSION]
target/debug/coreutils expr [OPTIONS]


Arguments:
  [expression]...  

Options:
      --version  output version information and exit
      --help     display this help and exit

Print the value of EXPRESSION to standard output.  A blank line below
separates increasing precedence groups.

Notice that there are no backticks around EXPRESSION. This change is not super helpful, but it functions as a proof of concept, I suppose.

Next steps

The next step is adding a full markdown parser and render more complicated markdown. We can play with colors, spacing, etc.. Afterwards, we can open issues to convert all utils to this format.

@tertsdiepraam tertsdiepraam force-pushed the markdown-in-docs-v1 branch 2 times, most recently from 9e3a937 to c1a5084 Compare November 19, 2022 11:17
@github-actions
Copy link

GNU testsuite comparison:

GNU test failed: tests/misc/tee. tests/misc/tee is passing on 'main'. Maybe you have to rebase?

@github-actions
Copy link

GNU testsuite comparison:

GNU test failed: tests/misc/tee. tests/misc/tee is passing on 'main'. Maybe you have to rebase?

@sylvestre sylvestre merged commit 3ca6139 into uutils:main Dec 2, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants