ongoing doc updates

[ev0net]

I created a better work flow to start regularly updating docs. I will keep this branch active and all modifications will be doc only.

I installed https://github.com/hestiacp/hestia-cli-docs and tested some different ways to create better example formatting. This renders correctly:

v-add-letsencrypt-domain:

# example: 
# # USAGE: [ALIASES] full subdomain(s) comma separated with no space i.e. www.domain.tld,sub.domain.tld
# # USAGE: [MAIL] certs for: mail.domain.tld + webmail.domain.tld | input-val: yes|no default-val: no
# # SSL cert only: domain.tld
# v-add-letsencrypt-domain username domain.tld
# # SSL certs for: domain.tld + www.domain.tld + sub.domain.tld NOTE: comma separated subdomains with no space
# v-add-letsencrypt-domain username domain.tld www.domain.tld,sub.domain.tld
# # Mail SSL certs only: mail.domain.tld + webmail.domain.tld
# v-add-letsencrypt-domain username domain.tld '' yes

Small formatting issue: changing lib/process-cmds.js line 192: .join('\n ') to .join('\n') fixes that. let me know if you prefer a pull request for that.

[ev0net]

Some forum topics:

https://forum.hestiacp.com/t/letsencrypt-cli-v-add-mail-domain-ssl-vs-gui-enable-ssl-for-this-domain-letsencrypt/11216/7

https://forum.hestiacp.com/t/weird-v-change-cron-job-behavior-collaborative-cli-documentation-updates/11507/11

[jaapmarcus]

Please do not wrap lines it should be handled by the editor or Vitepress

[ev0net]

It's your instructions TO wrap lines:

https://github.com/hestiacp/hestia-cli-docs#format the description is mandatory, delimited with empty line and consists of sentences wrapped for 80 width limit, each line is prepended with #

It's better readability in the file.

[ev0net]

I'm bumping this. I think it is better to have better documentation with worse formatting than worse documentation with better formatting.

[xeruf]

For one, I always recommend following https://sembr.org over character limits.
Then this has grammar issues, so here my suggestion:

# Fully replaces job parameters of an existing job, preserving its id.
# When executing commands, any output is mailed to the user's email 
# if user config parameter CRON_REPORTS is set to 'yes'. 

[jaapmarcus]

The code for CLI. Needs to be improved.. Ideally it should update every week the main branch somehow..

[ev0net]

The code for CLI. Needs to be improved.. Ideally it should update every week the main branch somehow..

Not sure what you are referring to.

All good with these changes?

[jaapmarcus]

For the CLI Doc generator.....

[ev0net]

The code for CLI. Needs to be improved.. Ideally it should update every week the main branch somehow..
For the CLI Doc generator.....

That would be cool!

BTW: I will do a pull request for the CLI Doc generator and fix:

Small formatting issue: changing lib/process-cmds.js line 192: .join('\n ') to .join('\n') fixes that. let me know if you prefer a pull request for that.

Add add this one time to the top of the template; NOT for each entry:

The intent is to explain non obvious arguments. i.e. we don't need to explain [USER] or [DOMAIN] every time. And [] indicates optional. Perhaps a new doc or doc header in cli.md with generic info like that?

[jaapmarcus]

I don't think updating it like this will improve the readability of the for the docs... We should improve first cli doc writer so we can remove the argument explanation outside the examples

[ev0net]

I don't think updating it like this will improve the readability of the for the docs...

I agree. But this is about improving the content. I think this is better than nothing, because someone should be able to use the CLI without looking at the code.

We should improve first cli doc writer so we can remove the argument explanation outside the examples

I agree. There should be a new block between options and examples called details or similar. details should allow for line breaks (unlike desc) However, I don't want get into learning the ins and outs javascript syntax right now.

Could you add this block to the cli doc writer?

In the meantime, could you merge these changes? They improve the content of the documentation, which saves everyone time.

Thanks!

[ev0net]

I'm bumping this. I think it is better to have better documentation with worse formatting than worse documentation with better formatting.

I would like to regularly contribute to the documentation. I find errors and omissions all the time but stopped correcting them because this pull request is stalled.

[ev0net]

I'm bumping this. I think it is better to have better documentation with worse formatting than worse documentation with better formatting.

[Aartsie]

How can I help here? If i'm understanding this correctly @jaapmarcus wants 2 things:

• A weekly update of the docs on the main branch
• Gets the Lint / Prettier fixed?

[jaapmarcus]

https://forum.hestiacp.com/t/changens-to-documentation/12952

[xeruf]

I don;t understand though why these lofty goals impede the merge of this straightforward PR

[jaapmarcus]

I don't want / have to rework everything again if we decide on a better format. It is a waste of our time... In the current suggested method it really sucks ... It doesn't improve readability ..

I think this is allready a huge improvement ...

Feel free to provide feed back in https://forum.hestiacp.com/t/changens-to-documentation/12952/6