testing docs

Testing local documentation builds

When writing docs for new features our policy is for you to test your build before submitting a PR. Make sure you have not introduced a critical bug. In general Asciidoctor is an excellent format for writers with minimal number of gotchas. However there are a few caveats that can bite.

Running a test build

This step assumes you have been working on a local checkout, and on your own feature branch.

1. make antora-uyuni-en or antora-suma-en

2. Review the following list while reviewing your work in the build directory index.html and pdf/

List of items to check

Look for the following after a successful build:

1. Check the left navigation, does it appear as you expect? This ensures you have closed your Asciidoctor blocks (tables, examples, callouts, admonitions etc).

2. Check the html and PDF output for the part of the document you worked on. Ensure you are getting the results you expect, again check that you have closed your adoc blocks properly.

3. Are your entities correct? {productname}, {productnumber} etc? PDF entities are currently stored in branding/pdf/entities.adoc. Entities must be adjusted here, and in suma-site.yml and uyuni-site.yml. We are working on a new process to reduce this to one configuration file

4. In the html output enter a search term then hover over the result. Verify that the url leads to the correct destination (D.S.C, ghpages. The webui currently should provide no search functionality)

5. Have you made branding changes? Has it affected the UI in any way?

6. After pushing a commit to your remote PR branch check GitHub actions to see if there are any failures, if so fix them or report the failure as an issue.