testing docs

Testing local documentation builds

Table of Contents

• Running a test build
• Visual Inspection

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.

Running a test build

1. Checkout a local clone of our git repository and ensure you have followed our toolchain installation guide.

2. If you already had the checkout, clean old stuff:

   make

3. Run configure for either Uyuni or SUSE Manager (one of them):

   make configure-uyuni
   make configure-suma

4. To save time, build an individual language (This will skip building static html and pdf documents for each language). Unless you are working with translations you should only ever need to run a build against the English locale. For example the following command will build the English outputs only for SUSE Manager (change suma to uyuni if you want Uyuni):

   make antora-suma-en

5. The following command will build all of our translated html pages and PDF documents (Required for publishing to documentation.suse.com):

   make antora-suma

6. Or, for Uyuni:

   make antora-uyuni

All documents are placed into the build/LANG/ directory.

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

Visual Inspection

Visually inspect your work after a successful build:

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

• 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.

• 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

• 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 products webui currently should provide no search functionality)

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

• 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.

• Does the build throw any noticeable errors? (Asciidoctor PDF or Antora)