Improve documentation guides

[Gustavo Marin]

In order to have a very thorough documentation, here you have an explanation on how the docs are automatically generated and published, and how you can contribute to improve it.

Where to create/modify guides?

Markdown docs can be found on the Hugo site folder on the docs branch.

The path for the guides is: docs/content/docs/guides, there you can modify or add new content.

Automatic CLI usage docs

On the same branch there is a directory where all content is generated automatically with a cobra feature to inspect and generate markdown.
So everything inside docs/content/docs/cli-usage is auto generated and will be overwritten on each run of the workflow.

Don't manually edit content there.

What to add?

• Anything that you consider useful for other users.

• Things you struggled with and found out how to solve.

• asciinema records that show how to use any feature. see how to below.

• Whatever you think is missing to better learn to use hostctl.

How to add content?

• First open a new issue to show your intentions about what would you like to write, that way the community can add to the discussion and help.

• Then fork it and checkout the docs branch.

• Create/add/modify any content you like.

• And finally open a PR to the docs branch

• (optional pro tip) If you add the text "Closes #999" on one of your commits with issue number you opened on the first step, it would be automatically closed when the PR is merged.

How to add asciinema casts

• Check asciinema Getting started if you don't know how to record.
• Once you have a cast file, ex: my_record.cast, add it to docs/static/my_record.cast directory on your PR.
• Modify a markdown file to include the player and your cast as the following example:

---
title: Some guide with a player
description: A great guide with an asciinema player
+asciinema: true
---

Some content... 

+{{<asciinema key="my_record.cast" >}}

...More content...