Changens to Documentation

As proposed in ongoing doc updates by ev0net · Pull Request #4110 · hestiacp/hestiacp · GitHub

The current CLI sucks quite a lot…

Current setup requires:

  1. Manual syncing and it sucks so it needs to be automated
  2. Info is often bare minimum and incomplete

With only the changes to the docs generator:

Proposed changes:

New format:

#!/bin/bash
# info: Generate Lets Encrypt certificate for provided domain and aliases.
# options: USER DOMAIN [ALIASES] [MAIL]
# variable: ALIASES | Comma separated list of aliases to be addd to the certificate this could contain up to 100 different domains / subdomain need to be under "ALIASES" under web
# variable: MAIL | Enable Lets encrypt from mail and webmail
# example: v-add-letsencrypt-domain user domain.com 'www.domain.com,demo.domain.com'
# example: v-add-letsencrypt-domain user domain.com '' yes
# Optional comments can still be made how ever not mixed with examples
# note: Wildcard domains *.domain.com are supported only when DNS via Hestia is used.
#!/bin/bash
# info:  General info regarding the function / script 
# options: Options  used 
# variable: Option name  |  Explaination regarding it can be multiple 
# example: script name   option1 option2 option3 can be multiple
# Optional comments can still be made how ever not mixed with examples 
# note:  Displayed in :::warning box  in vite press :::

Might place # note: with # info: and # warning:

Edit: # info can’t be used twice so kept note instead…

Anyone suggestion about it?

@Aartsie @evonet

Thanks for doing this @eris

  1. Generally I think it looks good and is sufficient to get the job done. I like the use of | to markup the variable name
  2. We need to create a cli document overview either at the top of the cli doc or as a separate doc. This would contain common common cli information used in multiple commands like output types like referenced in: [Feature] CLI Documentation FORMAT · Issue #4215 · hestiacp/hestiacp · GitHub
  3. If possible, a way to markup options line with default i.e. [RESTART:no]. While I know this can also be done on a variable line, but as a personal preference, I like knowing what the default behavior will be at a glance.
  4. If possible, full markdown/linebreak support in all sections would be helpful; when I played around with this linebreaks didn’t work and markdown only sometimes worked. I know you said you didn’t want to use markdown/vitepress the bash comments so I appreciate you adding it here to note section.
  5. Please address if you want lines wrapped or no wrapped per: ongoing doc updates by ev0net · Pull Request #4110 · hestiacp/hestiacp · GitHub + GitHub - hestiacp/hestia-cli-docs

Thanks!

1 Like
  1. Generally I think it looks good and is sufficient to get the job done. I like the use of | to markup the variable name

With the variables we have 3 issues:

  1. Often it is explanatory what it does but to many times it says something without any explanation…
  2. It is currently impossible to mean what it needs to contain “mail” in v-add-letsencrypt-domain means something else then “main” in v-restore-user …
  3. “Input” is impossible to guess what you need to input for example: “Restart”

We might need to split up in:

VAR | INPUT | Meanin
So

Notfication Numeric - Notification ID

  1. We need to create a cli document overview either at the top of the cli doc or as a separate doc. This would contain common common cli information used in multiple commands like output types like referenced in: [Feature] CLI Documentation FORMAT · Issue #4215 · hestiacp/hestiacp · GitHub

We should add notes about it on:

  1. If possible, full markdown/linebreak support in all sections would be helpful; when I played around with this linebreaks didn’t work and markdown only sometimes worked. I know you said you didn’t want to use markdown/vitepress the bash comments so I appreciate you adding it here to note section.

Have added both: “note” and “warning” for example:

  1. Note for “usefull” information for example: Wildcard *.domain.com is also a valid alias when you use Hestia DNS…
  2. Warning: When Disableling DNS it might break the domain …
  1. Please address if you want lines wrapped or no wrapped per: https://github.com/hestiacp/hestiacp/pull/4110#discussion_r1374910034 + GitHub - hestiacp/hestia-cli-docs

I don’t really see a reason to use wrapped lines. Most editors are able to handle word wrapping by it self it might be only useful

Restart is maybe the worst tag ever because Restart: “no” , “yes” or “” (Empty) does something else …

Restart no: No restart
Restart Yes: Runs always systemctl restart service
Restart “empty” or left out run: systemctl reload service (if supported)

  1. VAR FORMATTING

Yes. Having some sort of type indicator would be better even though the system is not adhering to strict data types. It sounds like you see the cli document issues, you are on board with improving it and since you are the one that is going to mod the doc generator, please do what you think is best.

  1. GENERIC CLI SECTION

I think we have a misunderstanding. I mean generic section related to cli usage, NOT how to create cli documentation For example, info from this post: [Feature] CLI Documentation FORMAT · Issue #4215 · hestiacp/hestiacp · GitHub
show details about output types. This doesn’t needed to be included in every cli command documentation subsection because this is common information. Only output types would be included in the subsection. Your [RESTART] info below is another example i.e.

In command subsection for variable:
[RESTART] see https://hestiacp.com/docs/reference/cli.html#generic-cli-usage-info

  1. MARKDOWN

Yes. Just saying linebreaks and some other markdown doesn’t work properly when doc generated. Not a big deal, but would be nice.

  1. WRAPPED LINES

Sounds good. Then you can remove the line " * the description is mandatory, delimited with empty line and consists of sentences wrapped for 80 width limit, each line is prepended with # from GitHub - hestiacp/hestia-cli-docs

Additionally, I think it would be good to put all the doc contribution info in one place. Just merge content of Contributing to Hestia’s documentation | Hestia Control Panel to README: GitHub - hestiacp/hestia-cli-docs AND put link to: GitHub - hestiacp/hestia-cli-docs in: Contributing to Hestia’s documentation | Hestia Control Panel

OTHER

Thanks for that explanation. I never understood how that worked. I also think the original developers should have used bash command flag functionality for that one anyway i.e. -r [restart]. But not something that I think is worth changing now.

“We” forked it originally from GitHub - bisubus/hestia-cli-docs: Provides pre-generated Hestia CLI documentation, as well as tools to generate it from annotation comments and keep it in a good shape as our “older” method sucked even more …

There also came the word wrap rules come from…

2 Likes

Thanks for that explanation. I never understood how that worked. I also think the original developers should have used bash command flag functionality for that one anyway i.e. -r [restart]. But not something that I think is worth changing now.

It is discussed In the past but a shit ton of work… :cry:

2 Likes