ci: Add markdownlint, test_converting_readme, and build_docs workflows

[spetrosi]

Enhancement: Add markdownlint, test_converting_readme, and build_docs GitHub workflows

Reason:

• markdownlint runs against markdown files to ensure correct syntax and avoid any issues with converting README.md to HTML
• test_converting_readme converts README.md > HTML and uploads this test artifact to ensure that conversion works fine
• build_docs converts README.md > HTML and pushes the result to the docs branch to publish dosc to GitHub pages site
• Rename commitlint.yml workflow into pr-title-lint for clarity

[spetrosi]

I also fix markdownlint issues on README.md and structure it.
After this is merged, you will be able to enable GitHub pages, build on branch docs from the docs/ directory. And then add URL to the page to the repo description like in https://github.com/linux-system-roles/ssh

[spetrosi]

Fixing ansible-lint errors in #247

[Jakuje]

the name does not match the command. I see only git installation here.

[spetrosi]

Fixed

[Jakuje]

I am good with the changes (except for the last note in README regarding the sshd_*. It rewrites a lot of documentation though so I would like to hear @mattwillsher opinion too.

[Jakuje]

we lost here the ... so I am not sure how intuitive this is going to be without that. In official documentation we have sshd_<OptionName>. Would using something like this work also here or can this be tweaked somehow to pass the linter?

https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/automating_system_administration_by_using_rhel_system_roles/index#sshd-system-role-variables_configuring-secure-communication-by-using-the-ssh-and-sshd-rhel-system-roles

[spetrosi]

Good catch, I missed this because markdownlint removed this automatically. markdownlint does not argue if I put ... or in a backtick. So, I used "sshd_<OptionName>" to be consistent with the official documentation.

[mattwillsher]

LGTM

[spetrosi]

Please merge

[spetrosi]

After this is merged, you will be able to enable GitHub pages, build on branch docs from the docs/ directory. And then add URL to the page to the repo description like, I believe you can keep the link to your ansible-galaxy that's there already and add a link to GitHub pages separated by a comma

[Jakuje]

@spetrosi sounds like the docs building failed after meging to master. Can you check what is the issue there or is just needed to allow the pages somewhere in the repo configuration?

[mattwillsher]

I think it needs a release build to generate the docs(?)

[spetrosi]

@Jakuje the workflows were configured to run on pushed to main, and ansible-sshd uses master branch. Fixing this in #253 please take a look.

[spetrosi]

I think it needs a release build to generate the docs(?)

Now, after master>main rename and after a PR that changes README.md has been merged, the docs are generated on docs branch. You now can enable GitHub pages - build on branch docs from the docs/ directory. And then add URL to the page to the repo description, like in https://github.com/linux-system-roles/ssh.

The next time you create a new release with https://github.com/linux-system-roles/auto-maintenance/blob/main/role-merge-prs.sh it will also generate .README.html within the PR that updates CHANGELOG.md.