Foreman documentation automated publishing

Hello,

I implemented Github Actions for our Foreman NG Documentation, it builds both HTML and PDF versions and validates all HTML links for each pull request. When content is pushed into master, it also publishes the HTML content via Github Pages at:

https://theforeman.github.io/foreman-documentation/

I have improved our linkchecker - it now uses linkchecker-tryer which retries HTML link check when it fails several times. We were hitting false alerts too often when remote would not respond, this hopefully solves it.

All the artifacts (HTML, PDF) are available for download for 90 days via Github Actions for each individual commit, including pull requests. The PDF files are currently not commited into gh-pages branch due to size (40 MB per commit) and nature (binary file), the plan is to use Github Releases to create a release every week so they are available for download to end users.

I would like to ask the docs team to review the process and test it, once confirmed we can ask our infra team to move the docs.theforeman.org DNS domain to Github so the content is server through Github instead. We can also decommission our current docs site running on our server after the switch.

I took the opportunity to clean up links a bit, books are available under /master/bookname instead of /web/guides/build which was a temporary URL as I could not figure out permissions on our server. After the switch we need to correct links from our official documentation as well as from discourse

3 Likes

One more incoming change, I also removed the weird “doc-” prefix from all book names. These are some naming conventions which are used in Red Hat Documentation teams, this patch removes that so the URLs are now really clean:

  • /master/Content_Management_Guide/index-foreman.html (Foreman build)
  • /master/Content_Management_Guide/index-foreman-deb.html (Foreman on Debian)
  • /master/Content_Management_Guide/index-satellite.html (Satellite build, not linked from our community site)

Cheers! Have a good one.